Re: [PATCH] doc: fix for out-of-tree builds of notmuch-emacs docs

[Tomi Ollila <tomi.ollila@iki.fi>]

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