From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id kNQIBiDY014IPAAA0tVLHw (envelope-from ) for ; Sun, 31 May 2020 16:15:28 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id OBzSASDY016CAwAA1q6Kng (envelope-from ) for ; Sun, 31 May 2020 16:15:28 +0000 Received: from arlo.cworth.org (arlo.cworth.org [50.126.95.6]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 471A49407C8 for ; Sun, 31 May 2020 16:15:25 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 593C86DE092F; Sun, 31 May 2020 09:15:20 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org 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 FJeMd76e3-df; Sun, 31 May 2020 09:15:19 -0700 (PDT) Received: from arlo.cworth.org (localhost [IPv6:::1]) by arlo.cworth.org (Postfix) with ESMTP id 157D96DE0319; Sun, 31 May 2020 09:15:19 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 7BCD26DE0319 for ; Sun, 31 May 2020 09:15:17 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org 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 AAurThV78ipI for ; Sun, 31 May 2020 09:15:15 -0700 (PDT) Received: from fethera.tethera.net (fethera.tethera.net [198.245.60.197]) by arlo.cworth.org (Postfix) with ESMTPS id 9AAEA6DE0314 for ; Sun, 31 May 2020 09:15:15 -0700 (PDT) Received: from remotemail by fethera.tethera.net with local (Exim 4.92) (envelope-from ) id 1jfQcC-0006Co-Gk; Sun, 31 May 2020 12:15:12 -0400 Received: (nullmailer pid 4100160 invoked by uid 1000); Sun, 31 May 2020 16:15:10 -0000 From: David Bremner To: David Bremner , Daniel Kahn Gillmor , Notmuch Mail Subject: [PATCH] doc: fix for out-of-tree builds of notmuch-emacs docs Date: Sun, 31 May 2020 13:15:03 -0300 Message-Id: <20200531161503.4100110-1-david@tethera.net> X-Mailer: git-send-email 2.26.2 In-Reply-To: <87k10sz3wb.fsf@tethera.net> References: <87k10sz3wb.fsf@tethera.net> MIME-Version: 1.0 X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: notmuch-bounces@notmuchmail.org Sender: "notmuch" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 50.126.95.6 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Spam-Score: 1.49 X-TUID: kft5exVYzBkN The sphinx-doc include directive does not have the ability to include files from the build tree, so we replace the include with reading the files in conf.py. The non-trivial downside of this is that the emacs docstrings are now defined for every rst source file. They are namespaced with docstring::, so hopefully there will not be any surprises. One thing that is noticable is a small (absolute) time penalty in running sphinx-doc. --- doc/Makefile.local | 2 +- doc/conf.py | 19 +++++++++++++++---- doc/notmuch-emacs.rst | 10 ---------- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/doc/Makefile.local b/doc/Makefile.local index b4e0c955..769438ed 100644 --- a/doc/Makefile.local +++ b/doc/Makefile.local @@ -4,7 +4,7 @@ dir := doc # You can set these variables from the command line. SPHINXOPTS := -q -SPHINXBUILD = WITH_EMACS=${WITH_EMACS} sphinx-build +SPHINXBUILD = WITH_EMACS=${WITH_EMACS} RSTI_DIR=$(realpath emacs) sphinx-build DOCBUILDDIR := $(dir)/_build # Internal variables. diff --git a/doc/conf.py b/doc/conf.py index fc9738ff..d8841d99 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -29,10 +29,21 @@ release = version # directories to ignore when looking for source files. exclude_patterns = ['_build'] -# If we don't have emacs (or the user configured --without-emacs), -# don't build the notmuch-emacs docs, as they need emacs to generate -# the docstring include files -if os.environ.get('WITH_EMACS') != '1': +if os.environ.get('WITH_EMACS') == '1': + # Hacky reimplementation of include to workaround limitations of + # sphinx-doc + accumulator='.. include:: /../emacs/rstdoc.rsti\n\n' # in the source tree + rsti_dir=os.environ.get('RSTI_DIR') + # the other files are from the build tree + for file in ['notmuch.rsti', 'notmuch-lib.rsti', 'notmuch-show.rsti', 'notmuch-tag.rsti']: + with open(rsti_dir+'/'+file) as f: + for line in f: + accumulator += line + rst_epilog=accumulator +else: + # If we don't have emacs (or the user configured --without-emacs), + # don't build the notmuch-emacs docs, as they need emacs to generate + # the docstring include files exclude_patterns.append('notmuch-emacs.rst') # The name of the Pygments (syntax highlighting) style to use. diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst index 1655e2f0..de47b726 100644 --- a/doc/notmuch-emacs.rst +++ b/doc/notmuch-emacs.rst @@ -377,13 +377,3 @@ suffix exist it will be read instead (just one of these, chosen in this order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file`` options, ``notmuch-init-file`` is not read. - -.. include:: ../emacs/rstdoc.rsti - -.. include:: ../emacs/notmuch.rsti - -.. include:: ../emacs/notmuch-lib.rsti - -.. include:: ../emacs/notmuch-show.rsti - -.. include:: ../emacs/notmuch-tag.rsti -- 2.26.2