debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-21 18:38:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: fix for out-of-tree builds of notmuch-emacs docs

Browse source 
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.
This commit is contained in:
David Bremner 2020-05-31 13:15:03 -03:00
parent 16d073ebe8
commit ee8dba1c30
3 changed files with 15 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/Makefile.local
View file

@ -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.

18
doc/conf.py
View file

@ -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.

10
doc/notmuch-emacs.rst
View file

@ -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