On Sun, May 31 2020, David Bremner wrote: > 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. IMO good enough tolerable hack to get this done for no (read: I don't know alternatives). Some comments below... > --- > doc/Makefile.local | 2 +- > doc/conf.py | 19 +++++++++++++++---- > doc/notmuch-emacs.rst | 10 ---------- > 3 files changed, 16 insertions(+), 15 deletions(-) > > diff --git a/doc/Makefile.local b/doc/Makefile.local > index b4e0c955..769438ed 100644 > --- a/doc/Makefile.local > +++ b/doc/Makefile.local > @@ -4,7 +4,7 @@ dir := doc > > # You can set these variables from the command line. > SPHINXOPTS := -q > -SPHINXBUILD = WITH_EMACS=${WITH_EMACS} sphinx-build > +SPHINXBUILD = WITH_EMACS=${WITH_EMACS} RSTI_DIR=$(realpath emacs) sphinx-build I was about to comment the above, before realized $(realpath ...) executes GNU Make function instead of system command :) ... > DOCBUILDDIR := $(dir)/_build > > # Internal variables. > diff --git a/doc/conf.py b/doc/conf.py > index fc9738ff..d8841d99 100644 > --- a/doc/conf.py > +++ b/doc/conf.py > @@ -29,10 +29,21 @@ 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 > + accumulator='.. include:: /../emacs/rstdoc.rsti\n\n' # in the source tree accumulator=['.. include:: /../emacs/rstdoc.rsti\n\n' # in the source tree] (in list, see below) > + rsti_dir=os.environ.get('RSTI_DIR') spaces around '=' > + # the other files are from the build tree > + for file in ['notmuch.rsti', 'notmuch-lib.rsti', 'notmuch-show.rsti', 'notmuch-tag.rsti']: tuple ('notmuch.rsti', 'notmuch-lib.rsti', ...) could have been used > + with open(rsti_dir+'/'+file) as f: > + for line in f: > + accumulator += line > + rst_epilog=accumulator accumulator.append(open(rsti_dir + '/' + file).read()) accumulator = ''.join(accumulator) rst_epilog = accumulator alternative last 2 lines rst_epilog = ''.join(accumulator) del accumulator (I personally would have left 'accumulator' away and used 'rst_epilog' directly (and perhaps commented its use as temporary list type).) > +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. Tomi _______________________________________________ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch