unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* [PATCH 1/2] doc: replace use of environment variables with a generated config
@ 2020-07-11 13:20 David Bremner
  2020-07-11 13:20 ` [PATCH 2/2] doc: add new python bindings to main documentatation tree David Bremner
                   ` (2 more replies)
  0 siblings, 3 replies; 13+ messages in thread
From: David Bremner @ 2020-07-11 13:20 UTC (permalink / raw)
  To: notmuch; +Cc: flub, 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

^ permalink raw reply related	[flat|nested] 13+ messages in thread

* [PATCH 2/2] doc: add new python bindings to main documentatation tree.
  2020-07-11 13:20 [PATCH 1/2] doc: replace use of environment variables with a generated config David Bremner
@ 2020-07-11 13:20 ` David Bremner
  2020-07-12 12:02   ` [PATCH] doc: set up for autoapi / readthedocs compatibility David Bremner
  2020-07-14 21:21   ` [PATCH 2/2] doc: add new python bindings to main documentatation tree Floris Bruynooghe
  2020-07-11 14:00 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Tomi Ollila
  2020-07-14 21:15 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Floris Bruynooghe
  2 siblings, 2 replies; 13+ messages in thread
From: David Bremner @ 2020-07-11 13:20 UTC (permalink / raw)
  To: notmuch; +Cc: flub, 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

^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH 1/2] doc: replace use of environment variables with a generated config
  2020-07-11 13:20 [PATCH 1/2] doc: replace use of environment variables with a generated config David Bremner
  2020-07-11 13:20 ` [PATCH 2/2] doc: add new python bindings to main documentatation tree David Bremner
@ 2020-07-11 14:00 ` Tomi Ollila
  2020-07-14 21:43   ` Floris Bruynooghe
  2020-07-15 12:28   ` David Bremner
  2020-07-14 21:15 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Floris Bruynooghe
  2 siblings, 2 replies; 13+ messages in thread
From: Tomi Ollila @ 2020-07-11 14:00 UTC (permalink / raw)
  To: David Bremner, notmuch; +Cc: flub, David Bremner

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH] doc: set up for autoapi / readthedocs compatibility
  2020-07-11 13:20 ` [PATCH 2/2] doc: add new python bindings to main documentatation tree David Bremner
@ 2020-07-12 12:02   ` David Bremner
  2020-07-14 21:42     ` Floris Bruynooghe
  2020-07-14 21:21   ` [PATCH 2/2] doc: add new python bindings to main documentatation tree Floris Bruynooghe
  1 sibling, 1 reply; 13+ messages in thread
From: David Bremner @ 2020-07-12 12:02 UTC (permalink / raw)
  To: David Bremner, notmuch; +Cc: flub

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

^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH 1/2] doc: replace use of environment variables with a generated config
  2020-07-11 13:20 [PATCH 1/2] doc: replace use of environment variables with a generated config David Bremner
  2020-07-11 13:20 ` [PATCH 2/2] doc: add new python bindings to main documentatation tree David Bremner
  2020-07-11 14:00 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Tomi Ollila
@ 2020-07-14 21:15 ` Floris Bruynooghe
  2020-07-17 10:07   ` Tomi Ollila
  2 siblings, 1 reply; 13+ messages in thread
From: Floris Bruynooghe @ 2020-07-14 21:15 UTC (permalink / raw)
  To: David Bremner, notmuch; +Cc: David Bremner

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)

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH 2/2] doc: add new python bindings to main documentatation tree.
  2020-07-11 13:20 ` [PATCH 2/2] doc: add new python bindings to main documentatation tree David Bremner
  2020-07-12 12:02   ` [PATCH] doc: set up for autoapi / readthedocs compatibility David Bremner
@ 2020-07-14 21:21   ` Floris Bruynooghe
  1 sibling, 0 replies; 13+ messages in thread
From: Floris Bruynooghe @ 2020-07-14 21:21 UTC (permalink / raw)
  To: David Bremner, notmuch; +Cc: David Bremner

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:

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: set up for autoapi / readthedocs compatibility
  2020-07-12 12:02   ` [PATCH] doc: set up for autoapi / readthedocs compatibility David Bremner
@ 2020-07-14 21:42     ` Floris Bruynooghe
  2020-07-15 11:53       ` David Bremner
  0 siblings, 1 reply; 13+ messages in thread
From: Floris Bruynooghe @ 2020-07-14 21:42 UTC (permalink / raw)
  To: David Bremner, David Bremner, notmuch

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.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH 1/2] doc: replace use of environment variables with a generated config
  2020-07-11 14:00 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Tomi Ollila
@ 2020-07-14 21:43   ` Floris Bruynooghe
  2020-07-15 12:28   ` David Bremner
  1 sibling, 0 replies; 13+ messages in thread
From: Floris Bruynooghe @ 2020-07-14 21:43 UTC (permalink / raw)
  To: Tomi Ollila, David Bremner, notmuch; +Cc: David Bremner

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.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: set up for autoapi / readthedocs compatibility
  2020-07-14 21:42     ` Floris Bruynooghe
@ 2020-07-15 11:53       ` David Bremner
  0 siblings, 0 replies; 13+ messages in thread
From: David Bremner @ 2020-07-15 11:53 UTC (permalink / raw)
  To: Floris Bruynooghe, notmuch; +Cc: Tomi Ollila

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH 1/2] doc: replace use of environment variables with a generated config
  2020-07-11 14:00 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Tomi Ollila
  2020-07-14 21:43   ` Floris Bruynooghe
@ 2020-07-15 12:28   ` David Bremner
  2020-07-15 12:36     ` [PATCH] configure: replace multiple redirects with redirected block David Bremner
  1 sibling, 1 reply; 13+ messages in thread
From: David Bremner @ 2020-07-15 12:28 UTC (permalink / raw)
  To: Tomi Ollila, notmuch; +Cc: flub

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH] configure: replace multiple redirects with redirected block
  2020-07-15 12:28   ` David Bremner
@ 2020-07-15 12:36     ` David Bremner
  2020-07-18 15:00       ` David Bremner
  0 siblings, 1 reply; 13+ messages in thread
From: David Bremner @ 2020-07-15 12:36 UTC (permalink / raw)
  To: David Bremner, Tomi Ollila, notmuch; +Cc: flub

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

^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH 1/2] doc: replace use of environment variables with a generated config
  2020-07-14 21:15 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Floris Bruynooghe
@ 2020-07-17 10:07   ` Tomi Ollila
  0 siblings, 0 replies; 13+ messages in thread
From: Tomi Ollila @ 2020-07-17 10:07 UTC (permalink / raw)
  To: Floris Bruynooghe, David Bremner, notmuch; +Cc: David Bremner

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] configure: replace multiple redirects with redirected block
  2020-07-15 12:36     ` [PATCH] configure: replace multiple redirects with redirected block David Bremner
@ 2020-07-18 15:00       ` David Bremner
  0 siblings, 0 replies; 13+ messages in thread
From: David Bremner @ 2020-07-18 15:00 UTC (permalink / raw)
  To: Tomi Ollila, notmuch

David Bremner <david@tethera.net> writes:

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

applied to master.

d

^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2020-07-18 15:00 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-07-11 13:20 [PATCH 1/2] doc: replace use of environment variables with a generated config David Bremner
2020-07-11 13:20 ` [PATCH 2/2] doc: add new python bindings to main documentatation tree David Bremner
2020-07-12 12:02   ` [PATCH] doc: set up for autoapi / readthedocs compatibility David Bremner
2020-07-14 21:42     ` Floris Bruynooghe
2020-07-15 11:53       ` David Bremner
2020-07-14 21:21   ` [PATCH 2/2] doc: add new python bindings to main documentatation tree Floris Bruynooghe
2020-07-11 14:00 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Tomi Ollila
2020-07-14 21:43   ` Floris Bruynooghe
2020-07-15 12:28   ` David Bremner
2020-07-15 12:36     ` [PATCH] configure: replace multiple redirects with redirected block David Bremner
2020-07-18 15:00       ` David Bremner
2020-07-14 21:15 ` [PATCH 1/2] doc: replace use of environment variables with a generated config Floris Bruynooghe
2020-07-17 10:07   ` Tomi Ollila

Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).