From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 3530B6DE12C2 for ; Sun, 20 Aug 2017 12:30:48 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" X-Spam-Flag: NO X-Spam-Score: 0.034 X-Spam-Level: X-Spam-Status: No, score=0.034 tagged_above=-999 required=5 tests=[AWL=0.054, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01] autolearn=disabled Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id q27G5PYk9_m1 for ; Sun, 20 Aug 2017 12:30:47 -0700 (PDT) Received: from mail-lf0-f65.google.com (mail-lf0-f65.google.com [209.85.215.65]) by arlo.cworth.org (Postfix) with ESMTPS id 198ED6DE12C0 for ; Sun, 20 Aug 2017 12:30:47 -0700 (PDT) Received: by mail-lf0-f65.google.com with SMTP id y15so9133720lfd.5 for ; Sun, 20 Aug 2017 12:30:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nikula-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :in-reply-to:references; bh=yND7WuunFa4TbXztU3y/o15Ez4rgPR19O+FAV48Qdy8=; b=CIcp79ME8oYrO5Kn5lAzgz7PEte0rHZFEsOnRm/i25aDblwVCeuiUd8GVnc0lBjl2c 83RAlfLJGC7gaTWo9jnxCxFbf4BOs8+wtT11PGPhVSff5jHGvMW6FOCYR6PFFUHTM3DB gMWZ6CfCOb4si3qDMnp+GPK3Dfks+kzTWHspCfYj+XVIzbw5xcw+orNP9bdNvknmYbqK ihNswNAMC3t5D8gZEIDP3nUAz1hinkOzz7Y3rXYGHtLLa/Bcg+liGBrZaRPXB/hd16q/ orcFLp0TVU+EYFP9Lvzj4IWo+La1NdyVgBgjfvZHULCdpP/JOWWcGSKH0pd3mCrHVwc1 aVaQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:in-reply-to:references; bh=yND7WuunFa4TbXztU3y/o15Ez4rgPR19O+FAV48Qdy8=; b=IFip5brMQMYf92MN+0t++h2RscFZCYMUxa09OYrxtBNLDxWNC2V44Q/jURqJ3DddjY vGJX+dbrLBY9N2ab4+PoymOvb6pyVcjNbEhZiixXGDI67WkX99mS49nDhOMKtYwhLs9K 9O76DNyrGTjeB4DZrqIKi2oSO+DPba/V+DGE3tonZq8Ur3u2t9LiTKhumDttDaS71RKQ 1A/r0T29VoKR83fA9juCGE8UyzUBFUUSM1qPrUi6u/J5kv+39dV5pS6yA9BiQZAjW0jh 4LXKIVAHvve5yRTR0z5AIxcvxgmasJvGP+9q4UloqO+N04PXEIG8BN1h8cn/UqiozcLM pfGw== X-Gm-Message-State: AHYfb5gRv5tA6YwMH6jMW55duzPTvypVVJ2JIHmBgBU9hxJQI+bU8J9w cjv8yf7wx5zekrXzOUgZlg== X-Received: by 10.46.75.17 with SMTP id y17mr4700257lja.47.1503257445200; Sun, 20 Aug 2017 12:30:45 -0700 (PDT) Received: from localhost (mobile-access-5d6aa6-119.dhcp.inet.fi. [93.106.166.119]) by smtp.gmail.com with ESMTPSA id n25sm2006111lja.66.2017.08.20.12.30.44 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 20 Aug 2017 12:30:44 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Subject: [RFC PATCH 2/4] doc: use hawkmoth for generating libnotmuch api documentation Date: Sun, 20 Aug 2017 22:30:37 +0300 Message-Id: X-Mailer: git-send-email 2.11.0 In-Reply-To: References: In-Reply-To: References: X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 20 Aug 2017 19:30:48 -0000 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 API +=========== + +.. c:autodoc:: lib/notmuch.h + +SEE ALSO +======== + +**notmuch(1)** -- 2.11.0