[PATCH 1/2] doc: replace use of environment variables with a generated config

[PATCH 1/2] doc: replace use of environment variables with a generated config

[David Bremner]

I don't love the use of exec, but it is getting unwieldy to pass
configuration options on the sphinx-build command line, and I
anticipate further use of conditionals.
---
 configure          |  8 ++++++++
 doc/Makefile.local |  2 +-
 doc/conf.py        | 11 ++++++++---
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/configure b/configure
index 80cbac4f..177432db 100755
--- a/configure
+++ b/configure
@@ -1548,6 +1548,14 @@ NOTMUCH_HAVE_PYTHON3_PYTEST=${have_python3_pytest}
 PLATFORM=${platform}
 EOF
 
+cat > sphinx.config <<EOF
+# Generate by configure, run from doc/conf.py
+EOF
+if [ $WITH_EMACS = "1" ]; then
+    printf "tags.add('WITH_EMACS')\n" >> sphinx.config
+fi
+printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
+
 # Finally, after everything configured, inform the user how to continue.
 cat <<EOF
 
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 769438ed..598b6028 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} RSTI_DIR=$(realpath emacs) sphinx-build
+SPHINXBUILD   = sphinx-build
 DOCBUILDDIR      := $(dir)/_build
 
 # Internal variables.
diff --git a/doc/conf.py b/doc/conf.py
index 70987ac5..fdff2a2c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -22,6 +22,13 @@ for pathdir in ['.', '..']:
         with open(version_file,'r') as infile:
             version=infile.read().replace('\n','')
 
+# read generated config
+for pathdir in ['.', '..']:
+    conf_file = os.path.join(location,pathdir,'sphinx.config')
+    if os.path.exists(conf_file):
+        with open(conf_file,'r') as infile:
+            exec(''.join(infile.readlines()))
+
 # The full version, including alpha/beta/rc tags.
 release = version
 
@@ -29,12 +36,10 @@ release = version
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
-if os.environ.get('WITH_EMACS') == '1':
+if tags.has('WITH_EMACS'):
     # Hacky reimplementation of include to workaround limitations of
     # sphinx-doc
     lines = ['.. 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'):
         lines.extend(open(rsti_dir+'/'+file))
     rst_epilog = ''.join(lines)
-- 
2.27.0

[PATCH 2/2] doc: add new python bindings to main documentatation tree.

[David Bremner]

A seperate conf.py and doc directory will be needed if someone wants
to build the bindings docs separately from notmuch.
---
 configure               | 4 ++++
 doc/conf.py             | 8 ++++++++
 doc/index.rst           | 1 +
 doc/python-bindings.rst | 5 +++++
 4 files changed, 18 insertions(+)
 create mode 100644 doc/python-bindings.rst

diff --git a/configure b/configure
index 177432db..36fe4a9d 100755
--- a/configure
+++ b/configure
@@ -801,6 +801,7 @@ if [ $have_python3 -eq 1 ]; then
     if "$python" -c 'import cffi,setuptools; cffi.FFI().verify()' >/dev/null 2>&1; then
         printf "Yes.\n"
         have_python3_cffi=1
+        WITH_PYTHON_DOCS=1
     else
         printf "No (will not install CFFI-based python bindings).\n"
     fi
@@ -1554,6 +1555,9 @@ EOF
 if [ $WITH_EMACS = "1" ]; then
     printf "tags.add('WITH_EMACS')\n" >> sphinx.config
 fi
+if [ $WITH_PYTHON_DOCS = "1" ]; then
+    printf "tags.add('WITH_PYTHON')\n" >> sphinx.config
+fi
 printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
 
 # Finally, after everything configured, inform the user how to continue.
diff --git a/doc/conf.py b/doc/conf.py
index fdff2a2c..94e266af 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -4,6 +4,8 @@
 import sys
 import os
 
+extensions = [ 'sphinx.ext.autodoc' ]
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 
@@ -22,6 +24,9 @@ for pathdir in ['.', '..']:
         with open(version_file,'r') as infile:
             version=infile.read().replace('\n','')
 
+# for autodoc
+sys.path.insert(0, os.path.join(location, '..', 'bindings', 'python-cffi', 'notmuch2'))
+
 # read generated config
 for pathdir in ['.', '..']:
     conf_file = os.path.join(location,pathdir,'sphinx.config')
@@ -50,6 +55,9 @@ else:
     # the docstring include files
     exclude_patterns.append('notmuch-emacs.rst')
 
+if not tags.has('WITH_PYTHON'):
+    exclude_patterns.append('python-bindings.rst')
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
diff --git a/doc/index.rst b/doc/index.rst
index 4440d93a..a3bf3480 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -26,6 +26,7 @@ Contents:
    man7/notmuch-search-terms
    man1/notmuch-show
    man1/notmuch-tag
+   python-bindings
 
 Indices and tables
 ==================
diff --git a/doc/python-bindings.rst b/doc/python-bindings.rst
new file mode 100644
index 00000000..e1ad26ad
--- /dev/null
+++ b/doc/python-bindings.rst
@@ -0,0 +1,5 @@
+Python Bindings
+===============
+
+.. automodule:: notmuch2
+   :members:
-- 
2.27.0

[PATCH] doc: set up for autoapi / readthedocs compatibility

[David Bremner]

sphinx-autoapi seems nicer conceptually (it parses the docs rather
than importing them), but it also generates a ton of warnings, so
leave the default as autodoc.
---

You can see the results of this (for now) at https://notmuch.readthedocs.io/en/rtdtest/
We'd presumable want to integrate the whole tree somehow into notmuchmail.org

 doc/conf.py                                   | 42 ++++++++++---------
 doc/index.rst                                 |  3 +-
 doc/python-autoapi.rst                        |  5 +++
 ...python-bindings.rst => python-autodoc.rst} |  0
 doc/requirements.txt                          |  2 +
 5 files changed, 31 insertions(+), 21 deletions(-)
 create mode 100644 doc/python-autoapi.rst
 rename doc/{python-bindings.rst => python-autodoc.rst} (100%)
 create mode 100644 doc/requirements.txt

diff --git a/doc/conf.py b/doc/conf.py
index 94e266af..c34c03ac 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -4,7 +4,28 @@
 import sys
 import os
 
-extensions = [ 'sphinx.ext.autodoc' ]
+location = os.path.dirname(__file__)
+bindings_path =  os.path.join(location, '..', 'bindings', 'python-cffi','notmuch2')
+exclude_patterns = ['_build']
+
+# read generated config
+for pathdir in ['.', '..']:
+    conf_file = os.path.join(location,pathdir,'sphinx.config')
+    if os.path.exists(conf_file):
+        with open(conf_file,'r') as infile:
+            exec(''.join(infile.readlines()))
+
+if tags.has("AUTOAPI") or os.environ.get('READTHEDOCS') == 'True':
+    extensions = [ 'autoapi.extension' ]
+    autoapi_dirs = [ bindings_path ]
+    autoapi_add_toctree_entry = False
+    exclude_patterns.append('python-autodoc.rst')
+elif tags.has('WITH_PYTHON'):
+    extensions = [ 'sphinx.ext.autodoc' ]
+    sys.path.insert(0, bindings_path)
+    exclude_patterns.append('python-autoapi.rst')
+else:
+    exclude_patterns.append('python-autodoc.rst', 'python-autoapi.rst')
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -16,31 +37,15 @@ master_doc = 'index'
 project = u'notmuch'
 copyright = u'2009-2020, Carl Worth and many others'
 
-location = os.path.dirname(__file__)
-
 for pathdir in ['.', '..']:
     version_file = os.path.join(location,pathdir,'version')
     if os.path.exists(version_file):
         with open(version_file,'r') as infile:
             version=infile.read().replace('\n','')
 
-# for autodoc
-sys.path.insert(0, os.path.join(location, '..', 'bindings', 'python-cffi', 'notmuch2'))
-
-# read generated config
-for pathdir in ['.', '..']:
-    conf_file = os.path.join(location,pathdir,'sphinx.config')
-    if os.path.exists(conf_file):
-        with open(conf_file,'r') as infile:
-            exec(''.join(infile.readlines()))
-
 # The full version, including alpha/beta/rc tags.
 release = version
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
-
 if tags.has('WITH_EMACS'):
     # Hacky reimplementation of include to workaround limitations of
     # sphinx-doc
@@ -55,9 +60,6 @@ else:
     # the docstring include files
     exclude_patterns.append('notmuch-emacs.rst')
 
-if not tags.has('WITH_PYTHON'):
-    exclude_patterns.append('python-bindings.rst')
-
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
diff --git a/doc/index.rst b/doc/index.rst
index a3bf3480..3493d7b4 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -26,7 +26,8 @@ Contents:
    man7/notmuch-search-terms
    man1/notmuch-show
    man1/notmuch-tag
-   python-bindings
+   python-autodoc
+   python-autoapi
 
 Indices and tables
 ==================
diff --git a/doc/python-autoapi.rst b/doc/python-autoapi.rst
new file mode 100644
index 00000000..fb968874
--- /dev/null
+++ b/doc/python-autoapi.rst
@@ -0,0 +1,5 @@
+Python Bindings
+===============
+
+.. autoapimodule:: notmuch2
+   :members:
diff --git a/doc/python-bindings.rst b/doc/python-autodoc.rst
similarity index 100%
rename from doc/python-bindings.rst
rename to doc/python-autodoc.rst
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 00000000..519ccd35
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,2 @@
+# for readthedocs, or other standalone builds of the docs.
+sphinx-autoapi
-- 
2.27.0

Re: [PATCH] doc: set up for autoapi / readthedocs compatibility

[Floris Bruynooghe]

On Sun 12 Jul 2020 at 09:02 -0300, David Bremner wrote:

> sphinx-autoapi seems nicer conceptually (it parses the docs rather
> than importing them),

TIL about sphinx-autoapi, agree it's nicer conceptually.

> but it also generates a ton of warnings, so
> leave the default as autodoc.
> ---
>
> You can see the results of this (for now) at https://notmuch.readthedocs.io/en/rtdtest/
> We'd presumable want to integrate the whole tree somehow into notmuchmail.org

Saldy it seems to struggle with a fair bit of things.  E.g. it does
manage to create a Database.MODE attribute, but it doesn't figure out
that this is the Mode enum and thus doesn't document the fact you have
two options: MODE.READ_ONLY and MODE.READ_WRITE.  There are obviously a
bunch of other enums where this matters.

It could be that these things are solvable by using more autodoc-style
directives:
https://sphinx-autoapi.readthedocs.io/en/latest/reference/directives.html

But I wonder if the autodoc one will always be better because of the
dynamic nature.  E.g. mapping notmuch2._database.Mode to
notmuch2.Database.MODE on the actual Public API.

I didn't actually try out how much better autodoc does, I should
probably try that too before commenting further.

Re: [PATCH] doc: set up for autoapi / readthedocs compatibility

[David Bremner]

Floris Bruynooghe <flub@devork.be> writes:

>
> I didn't actually try out how much better autodoc does, I should
> probably try that too before commenting further.

Thanks to both of you for feedback. I've applied the first two to
master.

It seems tricky to have autodoc on readthedocs without having notmuch2
in pip.  That seems like a lot of work just to have readthedocs work
(although obviously some people would be happy with it for other
reasons).

If we can't make autoapi work well enough, perhaps we can supplement /
replace the rtd version with a pointer to a self hosted version.

We should do the self hosted version of the HTML output from sphinx in
either case. I'm not sure it will fit nicely into the ikiwiki based
wiki, but it should be possible to deploy it on notmuchmail.org outside
the wiki.

d

Re: [PATCH 2/2] doc: add new python bindings to main documentatation tree.

[Floris Bruynooghe]

Oh, this is very nice!  I've been thinking for a while I should attempt
this.  Great to see it being done!

On Sat 11 Jul 2020 at 10:20 -0300, David Bremner wrote:

> A seperate conf.py and doc directory will be needed if someone wants
> to build the bindings docs separately from notmuch.
> ---
>  configure               | 4 ++++
>  doc/conf.py             | 8 ++++++++
>  doc/index.rst           | 1 +
>  doc/python-bindings.rst | 5 +++++
>  4 files changed, 18 insertions(+)
>  create mode 100644 doc/python-bindings.rst
>
> diff --git a/configure b/configure
> index 177432db..36fe4a9d 100755
> --- a/configure
> +++ b/configure
> @@ -801,6 +801,7 @@ if [ $have_python3 -eq 1 ]; then
>      if "$python" -c 'import cffi,setuptools; cffi.FFI().verify()' >/dev/null 2>&1; then
>          printf "Yes.\n"
>          have_python3_cffi=1
> +        WITH_PYTHON_DOCS=1
>      else
>          printf "No (will not install CFFI-based python bindings).\n"
>      fi
> @@ -1554,6 +1555,9 @@ EOF
>  if [ $WITH_EMACS = "1" ]; then
>      printf "tags.add('WITH_EMACS')\n" >> sphinx.config
>  fi
> +if [ $WITH_PYTHON_DOCS = "1" ]; then
> +    printf "tags.add('WITH_PYTHON')\n" >> sphinx.config
> +fi
>  printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
>  
>  # Finally, after everything configured, inform the user how to continue.
> diff --git a/doc/conf.py b/doc/conf.py
> index fdff2a2c..94e266af 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -4,6 +4,8 @@
>  import sys
>  import os
>  
> +extensions = [ 'sphinx.ext.autodoc' ]
> +
>  # The suffix of source filenames.
>  source_suffix = '.rst'
>  
> @@ -22,6 +24,9 @@ for pathdir in ['.', '..']:
>          with open(version_file,'r') as infile:
>              version=infile.read().replace('\n','')
>  
> +# for autodoc
> +sys.path.insert(0, os.path.join(location, '..', 'bindings', 'python-cffi', 'notmuch2'))
> +
>  # read generated config
>  for pathdir in ['.', '..']:
>      conf_file = os.path.join(location,pathdir,'sphinx.config')
> @@ -50,6 +55,9 @@ else:
>      # the docstring include files
>      exclude_patterns.append('notmuch-emacs.rst')
>  
> +if not tags.has('WITH_PYTHON'):
> +    exclude_patterns.append('python-bindings.rst')
> +
>  # The name of the Pygments (syntax highlighting) style to use.
>  pygments_style = 'sphinx'
>  
> diff --git a/doc/index.rst b/doc/index.rst
> index 4440d93a..a3bf3480 100644
> --- a/doc/index.rst
> +++ b/doc/index.rst
> @@ -26,6 +26,7 @@ Contents:
>     man7/notmuch-search-terms
>     man1/notmuch-show
>     man1/notmuch-tag
> +   python-bindings
>  
>  Indices and tables
>  ==================
> diff --git a/doc/python-bindings.rst b/doc/python-bindings.rst
> new file mode 100644
> index 00000000..e1ad26ad
> --- /dev/null
> +++ b/doc/python-bindings.rst
> @@ -0,0 +1,5 @@
> +Python Bindings
> +===============
> +
> +.. automodule:: notmuch2
> +   :members:

Re: [PATCH 1/2] doc: replace use of environment variables with a generated config

[Tomi Ollila]

On Sat, Jul 11 2020, David Bremner wrote:

> I don't love the use of exec, but it is getting unwieldy to pass
> configuration options on the sphinx-build command line, and I
> anticipate further use of conditionals.

Perhaps less "opinions" in commit message.

(and as I think I don't comment 2/2, s/seperate/separate/ there)


> ---
>  configure          |  8 ++++++++
>  doc/Makefile.local |  2 +-
>  doc/conf.py        | 11 ++++++++---
>  3 files changed, 17 insertions(+), 4 deletions(-)
>
> diff --git a/configure b/configure
> index 80cbac4f..177432db 100755
> --- a/configure
> +++ b/configure
> @@ -1548,6 +1548,14 @@ NOTMUCH_HAVE_PYTHON3_PYTEST=${have_python3_pytest}
>  PLATFORM=${platform}
>  EOF
>  
> +cat > sphinx.config <<EOF
> +# Generate by configure, run from doc/conf.py
> +EOF
> +if [ $WITH_EMACS = "1" ]; then
> +    printf "tags.add('WITH_EMACS')\n" >> sphinx.config
> +fi
> +printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
> +

perhaps instead of multiple redirections to the file, 

{
    echo "# Generated by configure, run from doc/conf.py"
    echo
    if [ $WITH_EMACS = "1" ]; then
        printf "tags.add('WITH_EMACS')\n"
    fi 
    printf "rsti_dir = '%s'\n" "$(realpath emacs)"

} > sphinx.config
    
alternative (someone might think less readable... ;/):

 exec 3>&1 1> sphinx.config

 echo "# Generated by configure, run from doc/conf.py"
 ...

 exec 1>&3 3>&-


>  # Finally, after everything configured, inform the user how to continue.
>  cat <<EOF

Re: [PATCH 1/2] doc: replace use of environment variables with a generated config

[Floris Bruynooghe]

On Sat 11 Jul 2020 at 17:00 +0300, Tomi Ollila wrote:

> On Sat, Jul 11 2020, David Bremner wrote:
>
>> I don't love the use of exec, but it is getting unwieldy to pass
>> configuration options on the sphinx-build command line, and I
>> anticipate further use of conditionals.
>
> Perhaps less "opinions" in commit message.
>
> (and as I think I don't comment 2/2, s/seperate/separate/ there)
>
>
>> ---
>>  configure          |  8 ++++++++
>>  doc/Makefile.local |  2 +-
>>  doc/conf.py        | 11 ++++++++---
>>  3 files changed, 17 insertions(+), 4 deletions(-)
>>
>> diff --git a/configure b/configure
>> index 80cbac4f..177432db 100755
>> --- a/configure
>> +++ b/configure
>> @@ -1548,6 +1548,14 @@ NOTMUCH_HAVE_PYTHON3_PYTEST=${have_python3_pytest}
>>  PLATFORM=${platform}
>>  EOF
>>  
>> +cat > sphinx.config <<EOF
>> +# Generate by configure, run from doc/conf.py
>> +EOF
>> +if [ $WITH_EMACS = "1" ]; then
>> +    printf "tags.add('WITH_EMACS')\n" >> sphinx.config
>> +fi
>> +printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
>> +
>
> perhaps instead of multiple redirections to the file, 
>
> {
>     echo "# Generated by configure, run from doc/conf.py"
>     echo
>     if [ $WITH_EMACS = "1" ]; then
>         printf "tags.add('WITH_EMACS')\n"
>     fi 
>     printf "rsti_dir = '%s'\n" "$(realpath emacs)"
>
> } > sphinx.config
>     
> alternative (someone might think less readable... ;/):
>
>  exec 3>&1 1> sphinx.config
>
>  echo "# Generated by configure, run from doc/conf.py"
>  ...
>
>  exec 1>&3 3>&-

I'd probably prefer this last one, but I don't mind any of the solutions or
even the current one.

Re: [PATCH 1/2] doc: replace use of environment variables with a generated config

[David Bremner]

Tomi Ollila <tomi.ollila@iki.fi> writes:
>
> perhaps instead of multiple redirections to the file, 
>
> {
>     echo "# Generated by configure, run from doc/conf.py"
>     echo
>     if [ $WITH_EMACS = "1" ]; then
>         printf "tags.add('WITH_EMACS')\n"
>     fi 
>     printf "rsti_dir = '%s'\n" "$(realpath emacs)"
>
> } > sphinx.config
>     

Sorry, I dropped the ball there. I did actually make this change at some
point but I rebased it away. I can do a cleanup patch.

d

[PATCH] configure: replace multiple redirects with redirected block

[David Bremner]

This belatedly implements Tomi's suggestion from

     id:m25zaukv6u.fsf@guru.guru-group.fi
---
 configure | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/configure b/configure
index b4ee7f37..d3b843b9 100755
--- a/configure
+++ b/configure
@@ -1549,16 +1549,16 @@ NOTMUCH_HAVE_PYTHON3_PYTEST=${have_python3_pytest}
 PLATFORM=${platform}
 EOF
 
-cat > sphinx.config <<EOF
-# Generated by configure, run from doc/conf.py
-EOF
-if [ $WITH_EMACS = "1" ]; then
-    printf "tags.add('WITH_EMACS')\n" >> sphinx.config
-fi
-if [ $WITH_PYTHON_DOCS = "1" ]; then
-    printf "tags.add('WITH_PYTHON')\n" >> sphinx.config
-fi
-printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
+{
+    echo "# Generated by configure, run from doc/conf.py"
+    if [ $WITH_EMACS = "1" ]; then
+        echo "tags.add('WITH_EMACS')"
+    fi
+    if [ $WITH_PYTHON_DOCS = "1" ]; then
+        echo "tags.add('WITH_PYTHON')"
+    fi
+    printf "rsti_dir = '%s'\n" $(realpath emacs)
+} > sphinx.config
 
 # Finally, after everything configured, inform the user how to continue.
 cat <<EOF
-- 
2.27.0

Re: [PATCH] configure: replace multiple redirects with redirected block

[David Bremner]

David Bremner <david@tethera.net> writes:

> This belatedly implements Tomi's suggestion from
>
>      id:m25zaukv6u.fsf@guru.guru-group.fi

applied to master.

d

Re: [PATCH 1/2] doc: replace use of environment variables with a generated config

[Floris Bruynooghe]

On Sat 11 Jul 2020 at 10:20 -0300, David Bremner wrote:

> I don't love the use of exec, but it is getting unwieldy to pass

It's already a config file written in Python which is a terrible sin.
So no need to apologise, I think it makes sense in this context.

> configuration options on the sphinx-build command line, and I
> anticipate further use of conditionals.
> ---
>  configure          |  8 ++++++++
>  doc/Makefile.local |  2 +-
>  doc/conf.py        | 11 ++++++++---
>  3 files changed, 17 insertions(+), 4 deletions(-)
>
> diff --git a/configure b/configure
> index 80cbac4f..177432db 100755
> --- a/configure
> +++ b/configure
> @@ -1548,6 +1548,14 @@ NOTMUCH_HAVE_PYTHON3_PYTEST=${have_python3_pytest}
>  PLATFORM=${platform}
>  EOF
>  
> +cat > sphinx.config <<EOF
> +# Generate by configure, run from doc/conf.py

Minor insignificant typo: Generated

> +EOF
> +if [ $WITH_EMACS = "1" ]; then
> +    printf "tags.add('WITH_EMACS')\n" >> sphinx.config
> +fi
> +printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
> +
>  # Finally, after everything configured, inform the user how to continue.
>  cat <<EOF
>  
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index 769438ed..598b6028 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} RSTI_DIR=$(realpath emacs) sphinx-build
> +SPHINXBUILD   = sphinx-build
>  DOCBUILDDIR      := $(dir)/_build
>  
>  # Internal variables.
> diff --git a/doc/conf.py b/doc/conf.py
> index 70987ac5..fdff2a2c 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -22,6 +22,13 @@ for pathdir in ['.', '..']:
>          with open(version_file,'r') as infile:
>              version=infile.read().replace('\n','')
>  
> +# read generated config
> +for pathdir in ['.', '..']:
> +    conf_file = os.path.join(location,pathdir,'sphinx.config')
> +    if os.path.exists(conf_file):
> +        with open(conf_file,'r') as infile:
> +            exec(''.join(infile.readlines()))
> +
>  # The full version, including alpha/beta/rc tags.
>  release = version
>  
> @@ -29,12 +36,10 @@ release = version
>  # directories to ignore when looking for source files.
>  exclude_patterns = ['_build']
>  
> -if os.environ.get('WITH_EMACS') == '1':
> +if tags.has('WITH_EMACS'):
>      # Hacky reimplementation of include to workaround limitations of
>      # sphinx-doc
>      lines = ['.. 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'):
>          lines.extend(open(rsti_dir+'/'+file))
>      rst_epilog = ''.join(lines)

Re: [PATCH 1/2] doc: replace use of environment variables with a generated config

[Tomi Ollila]

On Tue, Jul 14 2020, Floris Bruynooghe wrote:

> On Sat 11 Jul 2020 at 10:20 -0300, David Bremner wrote:
>
>> I don't love the use of exec, but it is getting unwieldy to pass
>
> It's already a config file written in Python which is a terrible sin.
> So no need to apologise, I think it makes sense in this context.
>
>> configuration options on the sphinx-build command line, and I
>> anticipate further use of conditionals.
>> ---
>>  configure          |  8 ++++++++
>>  doc/Makefile.local |  2 +-
>>  doc/conf.py        | 11 ++++++++---
>>  3 files changed, 17 insertions(+), 4 deletions(-)
>>
>> diff --git a/configure b/configure
>> index 80cbac4f..177432db 100755
>> --- a/configure
>> +++ b/configure
>> @@ -1548,6 +1548,14 @@ NOTMUCH_HAVE_PYTHON3_PYTEST=${have_python3_pytest}
>>  PLATFORM=${platform}
>>  EOF
>>  
>> +cat > sphinx.config <<EOF
>> +# Generate by configure, run from doc/conf.py
>
> Minor insignificant typo: Generated

Just to tease David more, I think I had that fixed in my suggestion ;)
LFTM with this typo fixed.

Tomi

>
>> +EOF
>> +if [ $WITH_EMACS = "1" ]; then
>> +    printf "tags.add('WITH_EMACS')\n" >> sphinx.config
>> +fi
>> +printf "rsti_dir = '%s'\n" $(realpath emacs) >> sphinx.config
>> +
>>  # Finally, after everything configured, inform the user how to continue.
>>  cat <<EOF
>>  
>> diff --git a/doc/Makefile.local b/doc/Makefile.local
>> index 769438ed..598b6028 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} RSTI_DIR=$(realpath emacs) sphinx-build
>> +SPHINXBUILD   = sphinx-build
>>  DOCBUILDDIR      := $(dir)/_build
>>  
>>  # Internal variables.
>> diff --git a/doc/conf.py b/doc/conf.py
>> index 70987ac5..fdff2a2c 100644
>> --- a/doc/conf.py
>> +++ b/doc/conf.py
>> @@ -22,6 +22,13 @@ for pathdir in ['.', '..']:
>>          with open(version_file,'r') as infile:
>>              version=infile.read().replace('\n','')
>>  
>> +# read generated config
>> +for pathdir in ['.', '..']:
>> +    conf_file = os.path.join(location,pathdir,'sphinx.config')
>> +    if os.path.exists(conf_file):
>> +        with open(conf_file,'r') as infile:
>> +            exec(''.join(infile.readlines()))
>> +
>>  # The full version, including alpha/beta/rc tags.
>>  release = version
>>  
>> @@ -29,12 +36,10 @@ release = version
>>  # directories to ignore when looking for source files.
>>  exclude_patterns = ['_build']
>>  
>> -if os.environ.get('WITH_EMACS') == '1':
>> +if tags.has('WITH_EMACS'):
>>      # Hacky reimplementation of include to workaround limitations of
>>      # sphinx-doc
>>      lines = ['.. 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'):
>>          lines.extend(open(rsti_dir+'/'+file))
>>      rst_epilog = ''.join(lines)
> _______________________________________________
> notmuch mailing list -- notmuch@notmuchmail.org
> To unsubscribe send an email to notmuch-leave@notmuchmail.org