From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id IBIlOq4T1F57IwAA0tVLHw (envelope-from ) for ; Sun, 31 May 2020 20:29:34 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id KEctNq4T1F6jCgAAB5/wlQ (envelope-from ) for ; Sun, 31 May 2020 20:29:34 +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 4C93F9407C6 for ; Sun, 31 May 2020 20:29:32 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 571386DE0F43; Sun, 31 May 2020 13:29:26 -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 sOzjV1Bo9HIs; Sun, 31 May 2020 13:29:25 -0700 (PDT) Received: from arlo.cworth.org (localhost [IPv6:::1]) by arlo.cworth.org (Postfix) with ESMTP id 769A36DE0F22; Sun, 31 May 2020 13:29:24 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 6D91E6DE0F22 for ; Sun, 31 May 2020 13:29:22 -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 GMgdaza9dAw6 for ; Sun, 31 May 2020 13:29:19 -0700 (PDT) Received: from lahtoruutu.iki.fi (lahtoruutu.iki.fi [185.185.170.37]) by arlo.cworth.org (Postfix) with ESMTPS id 69F396DE0EF2 for ; Sun, 31 May 2020 13:29:17 -0700 (PDT) Received: from guru.guru-group.fi (unknown [IPv6:2a02:2380:1:9:5054:ff:feb7:a4bc]) (using TLSv1.2 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) (Authenticated sender: too) by lahtoruutu.iki.fi (Postfix) with ESMTPSA id 195EA1B00121; Sun, 31 May 2020 23:29:09 +0300 (EEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1590956949; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=G9RIrgOYtCx5luROrNc9NCcxGRafuRTDUWYInrtmOcw=; b=tmbcie23xc+6SLS7Tiniv1odMAr6f1hISH1FUC82NZmgfvRLEzBoMMHbPVIrW43OGSstap 4QA3eX8DqA0uPNLQKIdCiTUFhDe9Qa9UkgjGkJsU2LOfVyy8J2h7BSns/Z3eat3bYx+QXW rygHRsta+LLrr6Mo0GwFaamnW8mE9usxN6GU+0apwrUV9bTu4OocHa/FJJ2YO4sQHqxpaT UKZGHmNlXeGlCUv+EPs5kFwz4Z8Y3cSUfWDaC8LF2xHmvOFbNjPvyJnmwuqcZAAN4lv5mF Ga0r9FeHk9d6v/GUjpSxrl8QZY6+cIAqb44zM5yVT5YOkih9Bn+Fq+/3Hfkdqw== From: Tomi Ollila To: David Bremner , Daniel Kahn Gillmor , Notmuch Mail Subject: Re: [PATCH] doc: fix for out-of-tree builds of notmuch-emacs docs In-Reply-To: <20200531161503.4100110-1-david@tethera.net> References: <87k10sz3wb.fsf@tethera.net> <20200531161503.4100110-1-david@tethera.net> User-Agent: Notmuch/0.28.3+84~g41389bb (https://notmuchmail.org) Emacs/26.3 (x86_64-pc-linux-gnu) X-Face: HhBM'cA~ MIME-Version: 1.0 ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=iki.fi; s=lahtoruutu; t=1590956949; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=G9RIrgOYtCx5luROrNc9NCcxGRafuRTDUWYInrtmOcw=; b=ssDdUm9IfOOKvlmy4Ig/oneWGO2OWgJt91//Kr2GK3vnUUa3Jmx/BhcbN9pgpf5oPsnPjV 35puc+8192KAoUnln4bEgII5rXU/0UErcMPJp82tFcFsYfpZpk0JLW4TXGcQD1jP5VG7pZ EwqkxPs/P7ka324BwhAwcKvZeCEm6Wd0nhUHcBeWgbSErjvrpip4OpqIYV57VcAD6b2l1K 0efUtWb3r9zYfD2W+ExuIaOSWYtcn4J4LoPdRyHapeeMiroL8evVndi0RqaHyMz51prtyK uxC/eiW8mck/EUUHcskkAtKXIybhAsIbHM8OWb2kX9tViQ8gR1HPdOuRK8OrJQ== ARC-Seal: i=1; s=lahtoruutu; d=iki.fi; t=1590956949; a=rsa-sha256; cv=none; b=ickzN3HxSqPOMkClU8y6ro2SnNNgzWvOHB4iAwgdDtq1tk0Je4FMKbXFcuudZ3t1mSwyYq /8sa2xXmZwgtdVTY/rVRnPPz5HmMQp6/3w+hKaiCeuVb19p+Ycr4Jdseru/GLwbmGzjlBb ncHpk3vJFDZ6GghN6EGbW7P5f6SViGK2d58jfVa5llmUalFMcK3+eEASPpOGXAlNOMux5P 9ho11b+j4b5vnI/R0rxJINWmsIroQ62AjL3PbbZdj3aTiYf3112RMqVG0rXpC/fd/raEUj TmcoNeC+Rd/EtkmAd2NzwelL/JmsCWohXiyvJJCJ4lfZRLB3qWIPzmG/fC1GOw== ARC-Authentication-Results: i=1; ORIGINATING; auth=pass smtp.auth=too smtp.mailfrom=tomi.ollila@iki.fi 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=fail (body hash did not verify) header.d=iki.fi header.s=lahtoruutu header.b=tmbcie23; 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.99 X-TUID: fJETfKWRdiXI On Sun, May 31 2020, David Bremner wrote: > 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. IMO good enough tolerable hack to get this done for no (read: I don't know alternatives). Some comments below... > --- > 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 I was about to comment the above, before realized $(realpath ...) executes GNU Make function instead of system command :) ... > 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 accumulator=['.. include:: /../emacs/rstdoc.rsti\n\n' # in the source tree] (in list, see below) > + rsti_dir=os.environ.get('RSTI_DIR') spaces around '=' > + # the other files are from the build tree > + for file in ['notmuch.rsti', 'notmuch-lib.rsti', 'notmuch-show.rsti', 'notmuch-tag.rsti']: tuple ('notmuch.rsti', 'notmuch-lib.rsti', ...) could have been used > + with open(rsti_dir+'/'+file) as f: > + for line in f: > + accumulator += line > + rst_epilog=accumulator accumulator.append(open(rsti_dir + '/' + file).read()) accumulator = ''.join(accumulator) rst_epilog = accumulator alternative last 2 lines rst_epilog = ''.join(accumulator) del accumulator (I personally would have left 'accumulator' away and used 'rst_epilog' directly (and perhaps commented its use as temporary list type).) > +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. Tomi