From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id EKjPDkTZZWFklQAAgWs5BA (envelope-from ) for ; Tue, 12 Oct 2021 20:51:48 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id sPGKCkTZZWHpTgAA1q6Kng (envelope-from ) for ; Tue, 12 Oct 2021 18:51:48 +0000 Received: from mail.notmuchmail.org (nmbug.tethera.net [IPv6:2607:5300:201:3100::1657]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id AD747EF06 for ; Tue, 12 Oct 2021 20:51:47 +0200 (CEST) Received: from nmbug.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id 5859E2902E; Tue, 12 Oct 2021 14:51:39 -0400 (EDT) Received: from mail-lf1-x135.google.com (mail-lf1-x135.google.com [IPv6:2a00:1450:4864:20::135]) by mail.notmuchmail.org (Postfix) with ESMTPS id 8E5F226D91 for ; Tue, 12 Oct 2021 14:51:35 -0400 (EDT) Received: by mail-lf1-x135.google.com with SMTP id j5so998353lfg.8 for ; Tue, 12 Oct 2021 11:51:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nikula-org.20210112.gappssmtp.com; s=20210112; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=4KPnD6a+PeOUNXuBbtnrZ8Owgi0mHE0VzZQqO6abXBU=; b=ce7+/JsiDEvms8jtDyyNyezV1q5upj7asKqhFvnK+Z5eEoluuhKhamObNXDDVC0h8Z yWqj0AYKcC8hP1hql2f6AlIKjRZyjJBOdMqdmttZdhfOQyZ26IwnqsTTlyR/GCfTlTqG ckpAj8o9brZ0H+25SQvcXK0jto1C+hC5ssQ3eKIuA6eO+CQIta8eXlDIiHwnoRzyZpz+ tBexMAXKrATxlnslWpVyDE7FmWGOwp+lOqOVT0EhT5JnKmQ2P17CGo+pMAdlEW+yNGTj bAcizYZg/+Kxka6l25TjwtU5LoEY13yFYqz3Xg8/El6ty0EozzvYoiELv2a0YqG2fqDp xrpQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=4KPnD6a+PeOUNXuBbtnrZ8Owgi0mHE0VzZQqO6abXBU=; b=n26i/AHXo6+4SqZs/bz/kGQsvYgqRHrhpMWv9LzhvHrZInNu3Ca/yelK2K09BHgdRO A5L/q1c/b3MyfhE/aY0BmFKt9duHk5sDxRASBtOhSgoLnjIMxqX8fvVvLHVtHg+fYNEi o32H1qQ6hGrcPtaWpCurgiSC5SpOpRY3cslv48TaYwi3Xdp9toMh9XpzBsaywKmHOHk5 xXtKM6fg3sGpA1a23/nh4r3i/lRxaXjtK0O60WwmGBpuYwhNOV3MV87LCtWb7iDjQApj 1FCacsUzDCmXdzqFHkbtcU34+3ZYc84V0UBgbjXQlNJrsbnLhDvs+BsUgUqGlfTl9iVR aTMw== X-Gm-Message-State: AOAM530Fq3daO7mM5xarcgDRUIWPkkMJplUfE5qo4jp1/LYiljYkDs6+ EujX+UNay5jRxS9FpuXBjjWp1WlUqmOwiThT1p7OrA== X-Google-Smtp-Source: ABdhPJxG9iHRqk2zqbgfW3KXuSxfhi/DRSyVyxwtlwBlsZUF+f0n0kQY7V/C1hDHYztcMvh8IVjJsg== X-Received: by 2002:a05:6512:49b:: with SMTP id v27mr8010626lfq.37.1634064693068; Tue, 12 Oct 2021 11:51:33 -0700 (PDT) Received: from localhost (87-95-50-104.bb.dnainternet.fi. [87.95.50.104]) by smtp.gmail.com with ESMTPSA id i12sm1101413lfb.234.2021.10.12.11.51.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 12 Oct 2021 11:51:32 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Cc: jani@nikula.org Subject: [RFC 0/5] doc: api docs overhaul Date: Tue, 12 Oct 2021 21:51:22 +0300 Message-Id: <20211012185127.198348-1-jani@nikula.org> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 Message-ID-Hash: XMCAJCGQ4UVRFQIFK377XSWKG66YNFNT X-Message-ID-Hash: XMCAJCGQ4UVRFQIFK377XSWKG66YNFNT X-MailFrom: jani@nikula.org X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-notmuch.notmuchmail.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.1 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1634064708; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=QTQgscFxDn7hMRew1cffD8tSLS/GIhHC0yHFhMCK7QE=; b=ElHdw6cZk6bCkV4xtUAKjHc9nMPrO1GGxY7L6r5Ub7b1EVuNTFWxhBvk9d2iq/qZQ4pShI 3IgrTP2vjHCDKtabgIBOBNQyBTpf8dTg/1HoSE9Z5/7zFmJOaHH1ZH6KdDvoj4/Npglcne M8lt018TZoQxa/OXSIf0L6BSNbc/UJBoALM9PlOIUsiy0TfXjlTjWjO0MXrC5JkVfDH/Qq 8Wv5FgYg3RQOq5HEGtKUxQ1qrbfOCKY06VHdRic/Pi9BLLTL8EJTKdkUsdFaoJAUFziC5v E61IFgoDSjajeDzhoNxaeAFLd/grYznGtJGRPDoBRLvJNUgeShByrvPtsCH/Iw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1634064708; a=rsa-sha256; cv=none; b=g64+L5OalcLputAXJRwKH1MP32gLFAP1T1I3946HD0So3mX/u+8L9wBenZ1V9+FLHP0HFk DAiX0AJlqdyJxrYxqbrd03mbC4sFCEwgeH2t/Q8TVTyyEAEihfJt2+KdgLTjulehk2WsYY Z/P6PNyphdapU7ocfENobOv65FBqHNjR0AvmTW/I9PzV0xJvYHUPE4JMPNpl5wNNC6YmN8 nhb/B+Lhl4r+V2U25fBOnEqaqJXmXgXmQc05m+IS7/YKwwJgO/YMcpD8nW7YQMwrmrb3pK 75Jy6xvsuySKd6urgxAk8NlQUEWUxsjl4zDGm5mDjQgS7C0yAAWPuWG/Xjy01w== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=nikula-org.20210112.gappssmtp.com header.s=20210112 header.b="ce7+/Jsi"; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 2607:5300:201:3100::1657 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Spam-Score: -0.04 Authentication-Results: aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=nikula-org.20210112.gappssmtp.com header.s=20210112 header.b="ce7+/Jsi"; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 2607:5300:201:3100::1657 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: AD747EF06 X-Spam-Score: -0.04 X-Migadu-Scanner: scn0.migadu.com X-TUID: gbgcx5iEWjdw I have a pet project to incorporate C documentation comments written in reStructuredText to Sphinx based documentation [1]. For Notmuch needs, it replaces Doxygen with something that directly integrates with Sphinx through an extension. I've split the series to configure/build changes, functional code changes in notmuch.h, and comment changes in notmuch.h. With this, the 'make sphinx-html' build includes the API, with cross-references working across the man pages, etc. We didn't have this before. The main downside is that Hawkmoth is not available via distro packaging, only PyPI. BR, Jani. [1] https://github.com/jnikula/hawkmoth Jani Nikula (5): doc: replace doxygen with hawkmoth sphinx extension for api docs lib: remove enum names from typedefs lib: remove commented out NOTMUCH_DEPRECATED() lib: remove #ifndef __DOXYGEN__ conditions lib: documentation comment overhaul for 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 + lib/notmuch.h | 1986 +++++++++++++++++++++++------------------- 8 files changed, 1131 insertions(+), 1254 deletions(-) delete mode 100644 doc/doxygen.cfg create mode 100644 doc/man3/notmuch.rst -- 2.30.2