unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
From: Jani Nikula <jani@nikula.org>
To: notmuch@notmuchmail.org
Cc: jani@nikula.org
Subject: [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs
Date: Tue, 12 Oct 2021 21:51:23 +0300	[thread overview]
Message-ID: <20211012185127.198348-2-jani@nikula.org> (raw)
In-Reply-To: <20211012185127.198348-1-jani@nikula.org>

Hawkmoth is a Sphinx extension for incorporating documentation
comments from C source to Sphinx. For Notmuch API documentation needs,
Doxygen is overkill, and Hawkmoth also directly integrates with
Sphinx.

Hawkmoth is currently not packaged for distros, just PyPI. To try this
out on Debian:

$ sudo apt install python3-clang-11 python3-venv
$ python3 -m venv --system-site-packages .venv
$ . .venv/bin/activate
$ pip install hawkmoth
$ ./configure
$ make build-man sphinx-html

Note that Doxygen also depends on libclang; the additional dependency
are the clang python bindings.

Initially, there will be lots of warnings due to documentation comment
formatting. These will be fixed in separate changes.

For more information on Hawkmoth, see
https://github.com/jnikula/hawkmoth
---
 configure            |  27 ++--
 doc/.gitignore       |   1 -
 doc/Makefile.local   |  54 +++-----
 doc/conf.py          |  13 ++
 doc/doxygen.cfg      | 298 -------------------------------------------
 doc/index.rst        |   1 +
 doc/man3/notmuch.rst |   5 +
 7 files changed, 53 insertions(+), 346 deletions(-)
 delete mode 100644 doc/doxygen.cfg
 create mode 100644 doc/man3/notmuch.rst

diff --git a/configure b/configure
index 6c3a38f1098a..4d6c62645561 100755
--- a/configure
+++ b/configure
@@ -867,17 +867,6 @@ if [ $WITH_EMACS = "1" ]; then
     fi
 fi
 
-have_doxygen=0
-if [ $WITH_API_DOCS = "1" ] ; then
-    printf "Checking if doxygen is available... "
-    if command -v doxygen > /dev/null; then
-	printf "Yes.\n"
-	have_doxygen=1
-    else
-	printf "No (so will not install api docs)\n"
-    fi
-fi
-
 have_ruby_dev=0
 if [ $WITH_RUBY = "1" ] ; then
     printf "Checking for ruby development files... "
@@ -914,6 +903,15 @@ if [ $WITH_DOCS = "1" ] ; then
     else
 	printf "No (so will not install info pages).\n"
     fi
+    if [ $WITH_API_DOCS = "1" ] ; then
+	printf "Checking if hawkmoth is available... "
+	if ${python} -m hawkmoth -h > /dev/null 2>&1; then
+	    printf "Yes.\n"
+	else
+	    printf "No (so will not install api docs)\n"
+	    WITH_API_DOCS=0
+	fi
+    fi
 fi
 
 if [ $WITH_DESKTOP = "1" ]; then
@@ -1372,8 +1370,8 @@ HAVE_MAKEINFO=${have_makeinfo}
 # Whether there's an install-info binary available for installing info format documentation
 HAVE_INSTALL_INFO=${have_install_info}
 
-# Whether there's a doxygen binary available for building api documentation
-HAVE_DOXYGEN=${have_doxygen}
+# Whether there's hawkmoth sphinx extension available for building api documentation
+WITH_API_DOCS=${WITH_API_DOCS}
 
 # The directory to which desktop files should be installed
 desktop_dir = \$(prefix)/share/applications
@@ -1576,6 +1574,9 @@ EOF
     if [ $WITH_PYTHON_DOCS = "1" ]; then
 	echo "tags.add('WITH_PYTHON')"
     fi
+    if [ $WITH_API_DOCS = "1" ]; then
+        echo "tags.add('WITH_API_DOCS')"
+    fi
     printf "rsti_dir = '%s'\n" "$(cd emacs && pwd -P)"
 } > sphinx.config
 
diff --git a/doc/.gitignore b/doc/.gitignore
index bbb749fabda3..f25d695cccbf 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,3 +1,2 @@
 *.pyc
 /_build
-/config.dox
diff --git a/doc/Makefile.local b/doc/Makefile.local
index f476d1da46c9..10281a82efff 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -9,26 +9,31 @@ DOCBUILDDIR      := $(dir)/_build
 
 # Internal variables.
 ALLSPHINXOPTS   := $(SPHINXOPTS) $(srcdir)/$(dir)
-APIMAN		:= $(DOCBUILDDIR)/man/man3/notmuch.3
-DOXYFILE	:= $(srcdir)/$(dir)/doxygen.cfg
 
 MAN1_RST := $(wildcard $(srcdir)/doc/man1/*.rst)
+ifeq ($(WITH_API_DOCS),1)
+	MAN3_RST := $(wildcard $(srcdir)/doc/man3/*.rst)
+else
+	MAN3_RST :=
+endif
 MAN5_RST := $(wildcard $(srcdir)/doc/man5/*.rst)
 MAN7_RST := $(wildcard $(srcdir)/doc/man7/*.rst)
-MAN_RST_FILES := $(MAN1_RST) $(MAN5_RST) $(MAN7_RST)
+MAN_RST_FILES := $(MAN1_RST) $(MAN3_RST) $(MAN5_RST) $(MAN7_RST)
 ALL_RST_FILES := $(MAN_RST_FILES) $(srcdir)/doc/notmuch-emacs.rst
 
 MAN1_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN1_RST:.rst=.1))
+MAN3_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN3_RST:.rst=.3))
 MAN5_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN5_RST:.rst=.5))
 MAN7_ROFF := $(patsubst $(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN7_RST:.rst=.7))
-MAN_ROFF_FILES := $(MAN1_ROFF) $(MAN5_ROFF) $(MAN7_ROFF)
+MAN_ROFF_FILES := $(MAN1_ROFF) $(MAN3_ROFF) $(MAN5_ROFF) $(MAN7_ROFF)
 
 MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
 
 MAN1_TEXI := $(patsubst $(srcdir)/doc/man1/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN1_RST))
+MAN3_TEXI := $(patsubst $(srcdir)/doc/man3/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN3_RST))
 MAN5_TEXI := $(patsubst $(srcdir)/doc/man5/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN5_RST))
 MAN7_TEXI := $(patsubst $(srcdir)/doc/man7/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN7_RST))
-INFO_TEXI_FILES := $(MAN1_TEXI) $(MAN5_TEXI) $(MAN7_TEXI)
+INFO_TEXI_FILES := $(MAN1_TEXI) $(MAN3_TEXI) $(MAN5_TEXI) $(MAN7_TEXI)
 ifeq ($(WITH_EMACS),1)
 	INFO_TEXI_FILES += $(DOCBUILDDIR)/texinfo/notmuch-emacs.texi
 endif
@@ -37,7 +42,7 @@ INFO_INFO_FILES := $(INFO_TEXI_FILES:.texi=.info)
 
 .PHONY: sphinx-html sphinx-texinfo sphinx-info
 
-.PHONY: install-man build-man apidocs install-apidocs
+.PHONY: install-man build-man
 
 %.gz: %
 	rm -f $@ && gzip --no-name --stdout $^ > $@
@@ -48,13 +53,13 @@ endif
 
 sphinx-html: $(DOCBUILDDIR)/.html.stamp
 
-$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES)
+$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES) lib/notmuch.h
 	$(SPHINXBUILD) -b html -d $(DOCBUILDDIR)/html_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
 	touch $@
 
 sphinx-texinfo: $(DOCBUILDDIR)/.texi.stamp
 
-$(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES)
+$(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES) lib/notmuch.h
 	$(SPHINXBUILD) -b texinfo -d $(DOCBUILDDIR)/texinfo_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
 	touch $@
 
@@ -69,10 +74,10 @@ ${MAN_ROFF_FILES}: $(DOCBUILDDIR)/.roff.stamp
 # convey to make that a single invocation of this recipe builds all
 # of the roff files.  This prevents parallel make from starting an
 # instance of this recipe for each roff file.
-$(DOCBUILDDIR)/.roff.stamp: ${MAN_RST_FILES}
+$(DOCBUILDDIR)/.roff.stamp: ${MAN_RST_FILES} lib/notmuch.h
 ifeq ($(HAVE_SPHINX),1)
 	$(SPHINXBUILD) -b man -d $(DOCBUILDDIR)/man_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
-	for section in 1 5 7; do \
+	for section in 1 3 5 7; do \
 	    mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
 	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
 	done
@@ -82,25 +87,6 @@ else
 endif
 	touch $@
 
-install-man: install-apidocs
-
-ifeq ($(HAVE_DOXYGEN),1)
-MAN_GZIP_FILES += ${APIMAN}.gz
-apidocs: $(APIMAN)
-install-apidocs: ${APIMAN}.gz
-	mkdir -p "$(DESTDIR)$(mandir)/man3"
-	install -m0644 $(filter %.3.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man3
-
-$(APIMAN): $(dir)/config.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h
-	mkdir -p $(DOCBUILDDIR)/man/man3
-	doxygen $(DOXYFILE)
-	rm -f $(DOCBUILDDIR)/man/man3/_*.3
-	perl -pi -e 's/^[.]RI "\\fI/.RI "\\fP/' $(APIMAN)
-else
-apidocs:
-install-apidocs:
-endif
-
 # Do not try to build or install man pages if a man page converter is
 # not available.
 ifeq ($(HAVE_SPHINX),0)
@@ -117,6 +103,10 @@ install-man: ${MAN_GZIP_FILES}
 	install -m0644 $(filter %.5.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man5
 	install -m0644 $(filter %.7.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man7
 	cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
+ifeq ($(WITH_API_DOCS),1)
+	mkdir -m0755 -p "$(DESTDIR)$(mandir)/man3"
+	install -m0644 $(filter %.3.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man3
+endif
 endif
 
 ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO),11)
@@ -136,10 +126,6 @@ install-info: build-info
 	for file in $(INFO_INFO_FILES); do install-info $$file $(DESTDIR)$(infodir)/dir; done
 endif
 
-$(dir)/config.dox: version.stamp
-	echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@
-	echo "INPUT=${srcdir}/lib/notmuch.h" >> $@
-
 CLEAN := $(CLEAN) $(DOCBUILDDIR) $(DOCBUILDDIR)/.roff.stamp $(DOCBUILDDIR)/.texi.stamp
 CLEAN := $(CLEAN) $(DOCBUILDDIR)/.html.stamp
-CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/config.dox
+CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc
diff --git a/doc/conf.py b/doc/conf.py
index 1fbd102bd30c..126bb075be11 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -61,6 +61,12 @@ if not tags.has('WITH_PYTHON'):
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
+if tags.has('WITH_API_DOCS'):
+    extensions.append('hawkmoth')
+    cautodoc_root = os.path.join(location, '..')
+else:
+    exclude_patterns.append('man3/notmuch.rst')
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -172,6 +178,13 @@ man_pages = [
      [notmuch_authors], 1),
 ]
 
+if tags.has('WITH_API_DOCS'):
+    man_pages += [
+        ('man3/notmuch', 'notmuch',
+         u'notmuch library',
+         [notmuch_authors], 3),
+    ]
+
 # If true, show URL addresses after external links.
 #man_show_urls = False
 
diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
deleted file mode 100644
index 4a022de1ce9e..000000000000
--- a/doc/doxygen.cfg
+++ /dev/null
@@ -1,298 +0,0 @@
-# Doxyfile 1.8.4
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING      = UTF-8
-@INCLUDE	       =  "doc/config.dox"
-PROJECT_NUMBER         =
-PROJECT_BRIEF          =
-PROJECT_LOGO           =
-OUTPUT_DIRECTORY       = doc/_build
-CREATE_SUBDIRS         = NO
-OUTPUT_LANGUAGE        = English
-BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = YES
-ABBREVIATE_BRIEF       =
-ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = NO
-STRIP_FROM_PATH        =
-STRIP_FROM_INC_PATH    =
-SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = YES
-QT_AUTOBRIEF           = NO
-MULTILINE_CPP_IS_BRIEF = NO
-INHERIT_DOCS           = YES
-SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 8
-ALIASES                =
-OPTIMIZE_OUTPUT_FOR_C  = YES
-OPTIMIZE_OUTPUT_JAVA   = NO
-OPTIMIZE_FOR_FORTRAN   = NO
-OPTIMIZE_OUTPUT_VHDL   = NO
-EXTENSION_MAPPING      =
-MARKDOWN_SUPPORT       = YES
-AUTOLINK_SUPPORT       = YES
-BUILTIN_STL_SUPPORT    = NO
-CPP_CLI_SUPPORT        = NO
-SIP_SUPPORT            = NO
-IDL_PROPERTY_SUPPORT   = YES
-DISTRIBUTE_GROUP_DOC   = NO
-SUBGROUPING            = YES
-INLINE_GROUPED_CLASSES = NO
-INLINE_SIMPLE_STRUCTS  = NO
-TYPEDEF_HIDES_STRUCT   = YES
-LOOKUP_CACHE_SIZE      = 0
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = NO
-EXTRACT_PRIVATE        = NO
-EXTRACT_PACKAGE        = NO
-EXTRACT_STATIC         = NO
-EXTRACT_LOCAL_CLASSES  = YES
-EXTRACT_LOCAL_METHODS  = NO
-EXTRACT_ANON_NSPACES   = NO
-HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = NO
-HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = NO
-INTERNAL_DOCS          = NO
-CASE_SENSE_NAMES       = YES
-HIDE_SCOPE_NAMES       = NO
-SHOW_INCLUDE_FILES     = NO
-FORCE_LOCAL_INCLUDES   = NO
-INLINE_INFO            = YES
-SORT_MEMBER_DOCS       = NO
-SORT_BRIEF_DOCS        = NO
-SORT_MEMBERS_CTORS_1ST = NO
-SORT_GROUP_NAMES       = NO
-SORT_BY_SCOPE_NAME     = NO
-STRICT_PROTO_MATCHING  = NO
-GENERATE_TODOLIST      = NO
-GENERATE_TESTLIST      = NO
-GENERATE_BUGLIST       = NO
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS       =
-MAX_INITIALIZER_LINES  = 30
-SHOW_USED_FILES        = NO
-SHOW_FILES             = NO
-SHOW_NAMESPACES        = NO
-FILE_VERSION_FILTER    =
-LAYOUT_FILE            =
-CITE_BIB_FILES         =
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET                  = YES
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = NO
-WARN_FORMAT            = "$file:$line: $text"
-WARN_LOGFILE           =
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT_ENCODING         = UTF-8
-FILE_PATTERNS          =
-RECURSIVE              = NO
-EXCLUDE                =
-EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       =
-EXCLUDE_SYMBOLS        =
-EXAMPLE_PATH           =
-EXAMPLE_PATTERNS       =
-EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             =
-INPUT_FILTER           =
-FILTER_PATTERNS        =
-FILTER_SOURCE_FILES    = NO
-FILTER_SOURCE_PATTERNS =
-USE_MDFILE_AS_MAINPAGE =
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER         = NO
-INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = YES
-REFERENCED_BY_RELATION = NO
-REFERENCES_RELATION    = NO
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS              = NO
-VERBATIM_HEADERS       = NO
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX     = NO
-COLS_IN_ALPHA_INDEX    = 5
-IGNORE_PREFIX          =
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML          = NO
-HTML_OUTPUT            = html
-HTML_FILE_EXTENSION    = .html
-HTML_HEADER            =
-HTML_FOOTER            =
-HTML_STYLESHEET        =
-HTML_EXTRA_STYLESHEET  =
-HTML_EXTRA_FILES       =
-HTML_COLORSTYLE_HUE    = 220
-HTML_COLORSTYLE_SAT    = 100
-HTML_COLORSTYLE_GAMMA  = 80
-HTML_TIMESTAMP         = YES
-HTML_DYNAMIC_SECTIONS  = NO
-HTML_INDEX_NUM_ENTRIES = 100
-GENERATE_DOCSET        = NO
-DOCSET_FEEDNAME        = "Doxygen generated docs"
-DOCSET_BUNDLE_ID       = org.doxygen.Project
-DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
-DOCSET_PUBLISHER_NAME  = Publisher
-GENERATE_HTMLHELP      = NO
-CHM_FILE               =
-HHC_LOCATION           =
-GENERATE_CHI           = NO
-CHM_INDEX_ENCODING     =
-BINARY_TOC             = NO
-TOC_EXPAND             = NO
-GENERATE_QHP           = NO
-QCH_FILE               =
-QHP_NAMESPACE          = org.doxygen.Project
-QHP_VIRTUAL_FOLDER     = doc
-QHP_CUST_FILTER_NAME   =
-QHP_CUST_FILTER_ATTRS  =
-QHP_SECT_FILTER_ATTRS  =
-QHG_LOCATION           =
-GENERATE_ECLIPSEHELP   = NO
-ECLIPSE_DOC_ID         = org.doxygen.Project
-DISABLE_INDEX          = NO
-GENERATE_TREEVIEW      = NO
-ENUM_VALUES_PER_LINE   = 4
-TREEVIEW_WIDTH         = 250
-EXT_LINKS_IN_WINDOW    = NO
-FORMULA_FONTSIZE       = 10
-FORMULA_TRANSPARENT    = YES
-USE_MATHJAX            = NO
-MATHJAX_FORMAT         = HTML-CSS
-MATHJAX_RELPATH        = https://cdn.mathjax.org/mathjax/latest
-MATHJAX_EXTENSIONS     =
-MATHJAX_CODEFILE       =
-SEARCHENGINE           = YES
-SERVER_BASED_SEARCH    = NO
-EXTERNAL_SEARCH        = NO
-SEARCHENGINE_URL       =
-SEARCHDATA_FILE        = searchdata.xml
-EXTERNAL_SEARCH_ID     =
-EXTRA_SEARCH_MAPPINGS  =
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4
-EXTRA_PACKAGES         =
-LATEX_HEADER           =
-LATEX_FOOTER           =
-LATEX_EXTRA_FILES      =
-PDF_HYPERLINKS         = YES
-USE_PDFLATEX           = YES
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-LATEX_SOURCE_CODE      = NO
-LATEX_BIB_STYLE        = plain
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    =
-RTF_EXTENSIONS_FILE    =
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = YES
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options related to the DOCBOOK output
-#---------------------------------------------------------------------------
-GENERATE_DOCBOOK       = NO
-DOCBOOK_OUTPUT         = docbook
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX =
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = NO
-EXPAND_ONLY_PREDEF     = NO
-SEARCH_INCLUDES        = NO
-INCLUDE_PATH           =
-INCLUDE_FILE_PATTERNS  =
-PREDEFINED             = __DOXYGEN__
-EXPAND_AS_DEFINED      =
-SKIP_FUNCTION_MACROS   = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references
-#---------------------------------------------------------------------------
-TAGFILES               =
-GENERATE_TAGFILE       =
-ALLEXTERNALS           = NO
-EXTERNAL_GROUPS        = NO
-EXTERNAL_PAGES         = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = NO
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = NO
-DOT_NUM_THREADS        = 0
-DOT_FONTNAME           = Helvetica
-DOT_FONTSIZE           = 10
-DOT_FONTPATH           =
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-UML_LOOK               = NO
-UML_LIMIT_NUM_FIELDS   = 10
-TEMPLATE_RELATIONS     = NO
-INCLUDE_GRAPH          = NO
-INCLUDED_BY_GRAPH      = NO
-CALL_GRAPH             = NO
-CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = NO
-DIRECTORY_GRAPH        = NO
-DOT_IMAGE_FORMAT       = png
-INTERACTIVE_SVG        = NO
-DOT_PATH               =
-DOTFILE_DIRS           =
-MSCFILE_DIRS           =
-DOT_GRAPH_MAX_NODES    = 50
-MAX_DOT_GRAPH_DEPTH    = 0
-DOT_TRANSPARENT        = NO
-DOT_MULTI_TARGETS      = YES
-GENERATE_LEGEND        = NO
-DOT_CLEANUP            = YES
diff --git a/doc/index.rst b/doc/index.rst
index fbdcf779bdca..6d0a31360354 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -27,6 +27,7 @@ Contents:
    man7/notmuch-sexp-queries
    man1/notmuch-show
    man1/notmuch-tag
+   man3/notmuch
    python-bindings
 
 Indices and tables
diff --git a/doc/man3/notmuch.rst b/doc/man3/notmuch.rst
new file mode 100644
index 000000000000..05a5bbc41bbb
--- /dev/null
+++ b/doc/man3/notmuch.rst
@@ -0,0 +1,5 @@
+==========
+libnotmuch
+==========
+
+.. c:autodoc:: lib/notmuch.h
-- 
2.30.2

  reply	other threads:[~2021-10-12 18:51 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-10-12 18:51 [RFC 0/5] doc: api docs overhaul Jani Nikula
2021-10-12 18:51 ` Jani Nikula [this message]
2021-10-13  6:26   ` [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs Tomi Ollila
2021-10-13  9:02     ` Jani Nikula
2021-10-13 13:21   ` David Bremner
2021-10-12 18:51 ` [RFC 2/5] lib: remove enum names from typedefs Jani Nikula
2021-10-13 13:18   ` David Bremner
2021-10-13 13:28     ` Tomi Ollila
2021-10-13 14:04       ` Jani Nikula
2021-10-12 18:51 ` [RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED() Jani Nikula
2021-10-13 13:19   ` David Bremner
2021-10-13 14:04     ` Jani Nikula
2021-10-12 18:51 ` [RFC 4/5] lib: remove #ifndef __DOXYGEN__ conditions Jani Nikula
2021-10-12 18:51 ` [RFC 5/5] lib: documentation comment overhaul for hawkmoth Jani Nikula
2021-10-13 12:17 ` [RFC 0/5] doc: api docs overhaul David Bremner
2021-10-13 13:41   ` Jani Nikula
2021-10-13 13:59     ` David Bremner

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://notmuchmail.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20211012185127.198348-2-jani@nikula.org \
    --to=jani@nikula.org \
    --cc=notmuch@notmuchmail.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).