[RFC PATCH 2/4] doc: use hawkmoth for generating libnotmuch api documentation

[Jani Nikula]

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