Using manpage role references generates helpful links in html
documentation, while retaining the same boldface style in the man
pages.
The external man page site is configurable. The Debian manpage site
seems like a good fit for Notmuch.
Sphinx 4.0 changed the default value of man_make_section_directory
from False to True. We create the section directories and move the
files manually, so fix the immediate man build failure by disabling
the feature.
The Sphinx documentation on this [1] is confusing, and has the change
backwards. Git history says the default changed from False to True.
[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-man_make_section_directory
Building Notmuch on macOS is known to cause problems because the Notmuch
distribution archive contains two files named "version". These names
clash with the <version> header as defined in C++20. Therefore, the
existing naming will likely become a problem on other platforms as well,
once compilers adopt the new standard.
Signed-off-by: Ralph Seichter <github@seichter.de>
Amended-by: db s/keyword/header/ in commit message.
It is getting unwieldy to pass configuration options on the
sphinx-build command line, and I anticipate further use of
conditionals.
As far as I could tell, execing a string is the idiomatic way to
emulate include in Python.
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.
The extra flexibility of having both HAVE_EMACS (for yes, there is an
emacs we can use) and WITH_EMACS (the user wants emacs support) lead
to confusion and bugs. We now just force WITH_EMACS to 0 if no
suitable emacs is detected.
Since the docstrings are not built in the case of --without-emacs,
even if emacs is detected, don't let sphinx build the emacs docs. This
avoids a large number of error messages due to missing includes. It's
actually a bit surprising sphinx doesn't generate an error for the
missing include files.
By default, Sphinx tries to pre-process text through SmartyPants,
which attempts to convert ASCII quotes and dashes to Unicode
characters. Unfortunately, this mangles technical text such as command
lines. For instance, this excerpt from notmuch-tag.rst:
**notmuch** **tag** **--batch** [--input=<*filename*>]
got turned into:
notmuch tag –batch [–input=<filename>]
That's an en-dash and an em-dash respectively.
Not only are these characters visually confusing and could easily be
mistaken for a single dash, copying and pasting such command lines
into a terminal is doomed to result in incomprehensible error
messages.
* doc/conf.py: Disable SmartyPants.
No need to repeat mostly the same information twice in conf.py. We
probably want to have a corresponding texinfo document for all the man
pages. Python list comprehension to the rescue. (The reverse is not
true; we have a texinfo document for notmuch-emacs we don't want as a
man page.)
There should be no user visible changes.
Although this manual is far from complete, it may be helpful for
someone. In particular building it as part of the standard build
process makes it easier to find problems when editing the
notmuch-emacs-manual.
Avoid:
$ make HAVE_SPHINX=1 sphinx-html
python ./doc/mkdocdeps.py ./doc doc/_build doc/docdeps.mk
sphinx-build -b html -d doc/_build/doctrees -q ./doc doc/_build/html
Making output directory...
WARNING: html_static_path entry '/home/wking/src/notmuch/notmuch/doc/_static' does not exist
because we have no static source in doc/_static.
This is the output from sphinx-quickstart, massaged a bit, along with
our existing man pages converted to rst.
A skeleton notmuch-emacs manual is also included. It is not suitable
for end user use yet.
