diff options
author | David Bremner <david@tethera.net> | 2020-05-31 13:15:03 -0300 |
---|---|---|
committer | David Bremner <david@tethera.net> | 2020-06-01 09:07:50 -0300 |
commit | ee8dba1c3013a00c0d1185583ea084f8ce3699b7 (patch) | |
tree | 2c54906711a63e16845a34b02cb27cb191b517d0 /doc/conf.py | |
parent | 16d073ebe8fe062bb733165bdb10d7d2937616b5 (diff) |
doc: fix for out-of-tree builds of notmuch-emacs docs
The sphinx-doc include directive does not have the ability to include
files from the build tree, so we replace the include with reading the
files in conf.py. The non-trivial downside of this is that the emacs
docstrings are now defined for every rst source file. They are
namespaced with docstring::, so hopefully there will not be any
surprises. One thing that is noticable is a small (absolute) time
penalty in running sphinx-doc.
Diffstat (limited to 'doc/conf.py')
-rw-r--r-- | doc/conf.py | 18 |
1 files changed, 14 insertions, 4 deletions
diff --git a/doc/conf.py b/doc/conf.py index fc9738ff..ffb8ca1f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -29,10 +29,20 @@ release = version # directories to ignore when looking for source files. exclude_patterns = ['_build'] -# If we don't have emacs (or the user configured --without-emacs), -# don't build the notmuch-emacs docs, as they need emacs to generate -# the docstring include files -if os.environ.get('WITH_EMACS') != '1': +if os.environ.get('WITH_EMACS') == '1': + # Hacky reimplementation of include to workaround limitations of + # sphinx-doc + lines = ['.. include:: /../emacs/rstdoc.rsti\n\n'] # in the source tree + rsti_dir = os.environ.get('RSTI_DIR') + # the other files are from the build tree + for file in ('notmuch.rsti', 'notmuch-lib.rsti', 'notmuch-show.rsti', 'notmuch-tag.rsti'): + lines.extend(open(rsti_dir+'/'+file)) + rst_epilog = ''.join(lines) + del lines +else: + # If we don't have emacs (or the user configured --without-emacs), + # don't build the notmuch-emacs docs, as they need emacs to generate + # the docstring include files exclude_patterns.append('notmuch-emacs.rst') # The name of the Pygments (syntax highlighting) style to use. |