improve html docs

improve html docs

[David Bremner]

The main difference between the html docs and the man/info pages is
the existence of an index page (this might be possible to control for
the info pages as well, if someone was motivated). This series makes a
few small improvements in the index page, most notably tricking
sphinx-doc into adding links for nmbug and notmuch-setup. Sphinx
mostly feels pretty strongly that a given page should appear only once
in a toctree, but it _seems_ to be ok to have them in seperate
toctrees that just get smooshed together.

[PATCH 1/3] doc: reorganize sphinx toctree

[David Bremner]

This mainly affects the html output (although users generating epub or
pdf would also notice a change). The goal is twofold: make the TOC a
bit friendler and easier to navigate by introducing some hierarchy,
and allow links for nmbug and notmuch-setup.
---
 doc/command-line.rst | 36 ++++++++++++++++++++++++++++++++++++
 doc/index.rst        | 27 +++++----------------------
 doc/queries.rst      |  9 +++++++++
 3 files changed, 50 insertions(+), 22 deletions(-)
 create mode 100644 doc/command-line.rst
 create mode 100644 doc/queries.rst

diff --git a/doc/command-line.rst b/doc/command-line.rst
new file mode 100644
index 00000000..543a5f9e
--- /dev/null
+++ b/doc/command-line.rst
@@ -0,0 +1,36 @@
+Notmuch Command Line Interface
+==============================
+
+Main commands
+-------------
+
+.. toctree::
+   :titlesonly:
+
+   man1/notmuch
+   man1/notmuch-address
+   man1/notmuch-compact
+   man1/notmuch-config
+   man1/notmuch-count
+   man1/notmuch-dump
+   man1/notmuch-emacs-mua
+   man1/notmuch-git
+   man1/notmuch-insert
+   man1/notmuch-new
+   man1/notmuch-reindex
+   man1/notmuch-reply
+   man1/notmuch-restore
+   man1/notmuch-search
+   man1/notmuch-show
+   man1/notmuch-tag
+   man5/notmuch-hooks
+
+Aliases
+-------
+  
+.. toctree::
+   :titlesonly:
+
+   nmbug <man1/notmuch-git>
+   notmuch-setup <man1/notmuch>
+   
diff --git a/doc/index.rst b/doc/index.rst
index c380ee1d..6b84a15f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -2,34 +2,17 @@
 Welcome to notmuch's documentation!
 ===================================
 
-Contents:
+Content
+-------
 
 .. toctree::
    :titlesonly:
 
-   man1/notmuch
-   man1/notmuch-address
-   man1/notmuch-compact
-   man1/notmuch-config
-   man1/notmuch-count
-   man1/notmuch-dump
+   command-line
+   queries
    notmuch-emacs
-   man1/notmuch-emacs-mua
-   man1/notmuch-git
-   man5/notmuch-hooks
-   man1/notmuch-insert
-   man1/notmuch-new
-   man7/notmuch-properties
-   man1/notmuch-reindex
-   man1/notmuch-reply
-   man1/notmuch-restore
-   man1/notmuch-search
-   man7/notmuch-search-terms
-   man7/notmuch-sexp-queries
-   man1/notmuch-show
-   man1/notmuch-tag
    python-bindings
-
+   
 Indices and tables
 ==================
 
diff --git a/doc/queries.rst b/doc/queries.rst
new file mode 100644
index 00000000..b76e71e0
--- /dev/null
+++ b/doc/queries.rst
@@ -0,0 +1,9 @@
+Notmuch Queries
+===============
+
+.. toctree::
+   :titlesonly:
+
+   man7/notmuch-search-terms
+   man7/notmuch-sexp-queries
+   man7/notmuch-properties
-- 
2.35.2

[PATCH 2/3] doc: retitle notmuch-emacs manual

[David Bremner]

This makes the HTML TOC read more naturally. Add a label to make cross
referencing easier.
---
 doc/notmuch-emacs.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/notmuch-emacs.rst b/doc/notmuch-emacs.rst
index 970cd7b7..f486db6d 100644
--- a/doc/notmuch-emacs.rst
+++ b/doc/notmuch-emacs.rst
@@ -1,6 +1,8 @@
-=============
-notmuch-emacs
-=============
+.. _notmuch-emacs:
+
+==========================
+Emacs Frontend for Notmuch
+==========================
 
 About this Manual
 =================
-- 
2.35.2

[PATCH 3/3] doc: drop module index from ToC

[David Bremner]

There is only one module listed, so the index is not useful.
---
 doc/index.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/doc/index.rst b/doc/index.rst
index 6b84a15f..fec3e6c2 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -13,9 +13,8 @@ Content
    notmuch-emacs
    python-bindings
    
-Indices and tables
-==================
+Index and search
+-----------------
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-- 
2.35.2

[PATCH 4/4] doc: do not generate python module index

[David Bremner]

This currently seems unhelpful, and not generating it removes if from
the navigation bar, which prevents mis-clicking.
---
 doc/conf.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/conf.py b/doc/conf.py
index 7f94cbed..4da38fed 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -67,6 +67,8 @@ pygments_style = 'sphinx'
 # a list of builtin themes.
 html_theme = 'default'
 
+# prevent generation of python module index
+html_domain_indices=[]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
-- 
2.35.2

Re: [PATCH 1/3] doc: reorganize sphinx toctree

[David Bremner]

David Bremner <david@tethera.net> writes:

> This mainly affects the html output (although users generating epub or
> pdf would also notice a change). The goal is twofold: make the TOC a
> bit friendler and easier to navigate by introducing some hierarchy,
> and allow links for nmbug and notmuch-setup.

series applied to master.

d