| Age | Commit message (Collapse) | Author |
|---|
|
This is mostly just copying docstrings, but putting them into sections
makes them more discoverable.
|
|
|
|
|
|
|
|
Mainly this allows dropping the ad-hoc directive emacsvar
|
|
This allows us to eliminate the ad-hoc emacscmd directive / role, and
improve indexing.
doc/emacs: convert remaining uses of emacscmd to define-key
This allows us to remove the no-longer used object type.
|
|
This corresponds to flycheck commit
1702d2db3d8ba9bcb9b2bf810e791e907fcc3adc, which is apparently the last
time this file was modified (2018).
Embedding seems defensible since the file is evidently not changing
that much, and we need to change some labels to make it fit with the
not-just-emacs nature of notmuch docs.
|
|
This makes it easier to navigate the merged index of all of the
notmuch documentation.
|
|
This currently seems unhelpful, and not generating it removes if from
the navigation bar, which prevents mis-clicking.
|
|
Commit 306b7028d added the nmconfig role / directive. Unfortunately
the default of using the directive name in texinfo output is pretty
ugly, so attempt to make it more human readable by passing `objname`
to add_object_type invocation.
|
|
Previously only man page aliases were being added as symlinks. The
addition to man_pages in conf.py automatically propagates to the list
of generated info pages.
Installation of the new pages is handled by existing recipes.
|
|
This is mainly derived from the various help outputs from the script,
with some massaging of markup and addition of links.
|
|
A user asked about the thousands separator on IRC, and I had to check
the source.
|
|
This makes sure each configuration item is cross referenceable without
extra markup, and also adds index entries.
|
|
|
|
Previously the python-cffi bindings either failed to build, or built
for the wrong module by using the installed module.
The fix requires correction the module path, building the bindings
before docs, and helping python find the built libnotmuch.
Based on patch / discussion from Micheal Gruber [1]
[1]: id:cover.1634808719.git.git@grubix.eu
|
|
There is not much of a parser here yet, but it already does some
useful error reporting. Most functionality sketched in the
documentation is not implemented yet; detailed documentation will
follow with the implementation.
|
|
This is needed so that docstrings from notmuch-tree.el (in particular
notmuch-tree-toggle-order) can be used in the emacs documentation.
|
|
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.
|
|
A separate conf.py and doc directory (or will be needed if someone wants
to build the bindings docs separately from notmuch.
|
|
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.
|
|
This will still generate a warning about an excluded document in the
toctree, but it cuts down on the noise quite a lot.
|
|
|
|
|
|
We will want a user-facing place to record details about the use of
notmuch properties shortly. This establishes a new manual page for
that purpose.
|
|
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.
|
|
This new subcommand takes a set of search terms, and re-indexes the
list of matching messages.
|
|
These are the (tentative) changes for 0.23.5
|
|
|
|
Seems to make more sense than to have the same title for everything.
|
|
No functional changes.
|
|
Don't repeat the same stuff so much. We probably don't want to track
individual authors for man/texinfo pages anyway.
No user visible changes.
|
|
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.
|
|
This was overlooked when adding the man page.
|
|
Yes, it is 2016
|
|
Now it is accurate and provides more information to the
reader of the documents.
|
|
Add a tool to start composing an email in the Notmuch Emacs UI with
the specified subject, recipients, and message body.
|
|
This is needed so that the rst docs are converted to man and info
pages.
|
|
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 avoids having to recreate the update-man-versions rule
|
|
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.
|
