Hawkmoth [1] is a minimalistic Sphinx C Domain autodoc directive extension to incorporate formatted C source code comments into Sphinx based documentation, by yours truly.
This adds libnotmuch(3) man page to incorporate API documentation using the extension. The naming is intentional to not conflict with the Doxygen based man page, for now. Hawkmoth has a few advantages over Doxygen. It directly integrates with Sphinx, and allows reStructuredText syntax in the documentation comments. It's simple and minimal, without the overlap of Doxygen and Sphinx. Of course, there are some disadvantages as well. Hawkmoth is a project very much in the larval stage. It's not even packaged yet. It undoubtedly has plenty of unexpected issues and bugs. It only has one contributor to fix them. It only targets C documentation. Hawkmoth C parsing is based on Clang Python Bindings, but then Doxygen also depends on Clang. On Debian, the minimum dependencies are: * python-clang-3.8 * libclang-3.8-dev * libclang1-3.8 Unfortunately python-clang seems to be for Python 2 only, so you'll need to use Python 2 based Sphinx as well. (To be investigated.) As can be seen from the size of this patch, the simplicity of Hawkmoth makes it a compelling alternative for Sphinx based C API documentation. [1] https://github.com/jnikula/hawkmoth --- doc/conf.py | 14 ++++++++++++++ doc/index.rst | 1 + doc/man3/libnotmuch.rst | 20 ++++++++++++++++++++ 3 files changed, 35 insertions(+) create mode 100644 doc/man3/libnotmuch.rst diff --git a/doc/conf.py b/doc/conf.py index 0e65413d917a..4b25cfd4dbf2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -4,6 +4,9 @@ import sys import os +# FIXME: Use PYTHONPATH=$PYTHONPATH:/path/to/hawkmoth or this: +#sys.path.insert(0, os.path.abspath('/path/to/hawkmoth')) + # The suffix of source filenames. source_suffix = '.rst' @@ -32,6 +35,9 @@ exclude_patterns = ['_build'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# Extensions +extensions = ['cautodoc'] + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -126,6 +132,10 @@ man_pages = [ ('man1/notmuch-tag', 'notmuch-tag', u'add/remove tags for all messages matching the search terms', [notmuch_authors], 1), + + ('man3/libnotmuch', 'libnotmuch', + u'notmuch library API', + [notmuch_authors], 3), ] # If true, show URL addresses after external links. @@ -156,3 +166,7 @@ texinfo_documents += [ x[2], # description 'Miscellaneous' # category ) for x in man_pages] + +# cautodoc options +cautodoc_root = os.path.abspath('..') +cautodoc_compat = 'javadoc-liberal' diff --git a/doc/index.rst b/doc/index.rst index aa6c9f40462c..bbf0c6873b76 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -25,6 +25,7 @@ Contents: man7/notmuch-search-terms man1/notmuch-show man1/notmuch-tag + man3/libnotmuch Indices and tables ================== diff --git a/doc/man3/libnotmuch.rst b/doc/man3/libnotmuch.rst new file mode 100644 index 000000000000..0c583ccd00b9 --- /dev/null +++ b/doc/man3/libnotmuch.rst @@ -0,0 +1,20 @@ +========== +libnotmuch +========== + +SYNOPSIS +======== + +:: + + #include <notmuch.h> + +NOTMUCH API +=========== + +.. c:autodoc:: lib/notmuch.h + +SEE ALSO +======== + +**notmuch(1)** -- 2.11.0 _______________________________________________ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch
