Re: [PATCH] doc: fix for out-of-tree builds of notmuch-emacs docs
Tomi Ollila writes: > 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... Pushed a version with most of Tomi's comments applied (and s/append/extend/) d ___ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch
Re: [PATCH] doc: fix for out-of-tree builds of notmuch-emacs docs
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
[PATCH] 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. --- 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 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 +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']: +with open(rsti_dir+'/'+file) as f: +for line in f: +accumulator += line +rst_epilog=accumulator +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. diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst index 1655e2f0..de47b726 100644 --- a/doc/notmuch-emacs.rst +++ b/doc/notmuch-emacs.rst @@ -377,13 +377,3 @@ suffix exist it will be read instead (just one of these, chosen in this order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file`` options, ``notmuch-init-file`` is not read. - -.. include:: ../emacs/rstdoc.rsti - -.. include:: ../emacs/notmuch.rsti - -.. include:: ../emacs/notmuch-lib.rsti - -.. include:: ../emacs/notmuch-show.rsti - -.. include:: ../emacs/notmuch-tag.rsti -- 2.26.2 ___ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch