sphinx-toctree-signature.py

from sphinx.transforms import SphinxTransform
import sphinx.environment.collectors.toctree as toctree_collector
from sphinx import addnodes
from docutils import nodes


from typing import Any, Dict, List, Set, Tuple, Type, TypeVar, cast

from docutils import nodes
from docutils.nodes import Element, Node

from sphinx import addnodes
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx.environment.adapters.toctree import TocTree
from sphinx.environment.collectors import EnvironmentCollector
from sphinx.locale import __
from sphinx.transforms import SphinxContentsFilter
from sphinx.util import logging, url_re

N = TypeVar("N")

logger = logging.getLogger(__name__)


class SignatureContentsFilter(SphinxContentsFilter):
    # This logic is obtuse, but what's happening here is that we set up the
    # .parent array to hold a _container_ around a text node.
    # The `SkipNode` exception: https://github.com/docutils/docutils/blob/ae4d18314a821e61a24dc0e4f29a691b7c3b656e/docutils/docutils/nodes.py#L2159-L2164
    # ensures that the `default_depart` method: https://github.com/docutils/docutils/blob/ae4d18314a821e61a24dc0e4f29a691b7c3b656e/docutils/docutils/nodes.py#L2127-L2130
    # isn't called.
    # It also ensures the container's children aren't visited - we want to stop here
    # `fullname` is the qualified name of the documented object.
    def visit_desc_signature(self, node):
        # Replace this element with a simple element wrapping text
        self.parent.append(nodes.Element("", nodes.Text(node.attributes["fullname"])))
        raise nodes.SkipNode


# Most of this is copied from Sphinx
class BetterTocTreeCollector(toctree_collector.TocTreeCollector):
    def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
        """Build a TOC from the doctree and store it in the inventory."""
        docname = app.env.docname
        numentries = [0]  # nonlocal again...

        # This is changed to a generator, and the class condition removed
        def traverse_in_section(node: Element) -> List[N]:
            """Like traverse(), but stay within the same section."""
            yield node
            for child in node.children:
                if isinstance(child, nodes.section):
                    continue
                elif isinstance(child, nodes.Element):
                    yield from traverse_in_section(child)

        def build_toc(node: Element, depth: int = 1) -> nodes.bullet_list:
            # The logic here is a bit confusing.
            # It looks like section nodes are expected to be top-level within a section.
            entries: List[Element] = []

            for sectionnode in node:
                # find all toctree nodes in this section and add them
                # to the toc (just copying the toctree node which is then
                # resolved in self.get_and_resolve_doctree)
                if isinstance(sectionnode, nodes.section):
                    title = sectionnode[0]
                    # copy the contents of the section title, but without references
                    # and unnecessary stuff
                    visitor = SphinxContentsFilter(doctree)
                    title.walkabout(visitor)
                    nodetext = visitor.get_entry_text()
                    # if nodetext and nodetext[0] == "ak.ArrayBuilder":
                    # print(node)
                    # break
                    if not numentries[0]:
                        # for the very first toc entry, don't add an anchor
                        # as it is the file's title anyway
                        anchorname = ""
                    else:
                        anchorname = "#" + sectionnode["ids"][0]
                    numentries[0] += 1
                    # make these nodes:
                    # list_item -> compact_paragraph -> reference
                    reference = nodes.reference(
                        "",
                        "",
                        internal=True,
                        refuri=docname,
                        anchorname=anchorname,
                        *nodetext
                    )
                    para = addnodes.compact_paragraph("", "", reference)
                    item: Element = nodes.list_item("", para)
                    sub_item = build_toc(sectionnode, depth + 1)
                    if sub_item:
                        item += sub_item
                    entries.append(item)
                elif isinstance(sectionnode, addnodes.only):
                    onlynode = addnodes.only(expr=sectionnode["expr"])
                    blist = build_toc(sectionnode, depth)
                    if blist:
                        onlynode += blist.children
                        entries.append(onlynode)
                # Otherwise, for a generic element we allow recursion into the section
                elif isinstance(sectionnode, nodes.Element):
                    for node in traverse_in_section(sectionnode):
                        if isinstance(node, addnodes.toctree):
                            item = node.copy()
                            entries.append(item)
                            # important: do the inventory stuff
                            TocTree(app.env).note(docname, node)
                        # For signatures within some section, we add them to the ToC
                        elif isinstance(node, addnodes.desc_signature):
                            title = node
                            # Copy the signature, but without the detail e.g. parens
                            visitor = SignatureContentsFilter(doctree)
                            title.walkabout(visitor)
                            nodetext = visitor.get_entry_text()
                  
                            if not numentries[0]:
                                # for the very first toc entry, don't add an anchor
                                # as it is the file's title anyway
                                anchorname = ""
                            else:
                                anchorname = "#" + node["ids"][0]
                            numentries[0] += 1
                            # make these nodes:
                            # list_item -> compact_paragraph -> reference
                            reference = nodes.reference(
                                "",
                                "",
                                internal=True,
                                refuri=docname,
                                anchorname=anchorname,
                                *nodetext
                            )
                            para = addnodes.compact_paragraph("", "", reference)
                            item: Element = nodes.list_item("", para)
                            entries.append(item)
            if entries:
                return nodes.bullet_list("", *entries)
            return None

        toc = build_toc(doctree)
        assert docname in app.env.tocs
        if toc:
            app.env.tocs[docname] = toc
        else:
            app.env.tocs[docname] = nodes.bullet_list("")
        app.env.toc_num_entries[docname] = numentries[0]


def setup(app):
    app.add_env_collector(BetterTocTreeCollector)

I'll let you know if/when I tackle this @asmeurer. Right now it's lower on my priority list, but I will try and get to it eventually :)

You can use :titlesonly: in the toctree, perhaps?

Yes, this looks like exactly what we want. We really should be using this everywhere instead of :maxdepth:. Is there a similar option for the Furo left sidebar btw? For now, we can just require one H1 header per page, but it's annoying when a page doesn't follow that and its subheadings get put in the left sidebar.

https://github.com/pradyunsg/furo/blob/9f41ee678d68ee11d91b98ffbdc4f79a9fb8b99b/src/furo/__init__.py#L121

Furo already passes that, so... I reckon this is some sort of weird interaction of this code with Sphinx's toctree context variable?

https://github.com/sphinx-doc/sphinx/blob/e32301cbbb00e8a96ca2cf9b91f2d165b5d33780/sphinx/builders/html/__init__.py#L959

Oh wait, is that a single page with multiple h1s? If so, all the h1s will end up in the left sidebar and there's not much that Furo can do about that -- Sphinx's toctree context variable adds every h1 to the toctree HTML in that manner, with no real metadata to allow Furo to trim things. See https://pradyunsg.me/furo/kitchen-sink/structure/#structural-elements-2 for example.

Besides, restricting pages to have a single h1 is the right thing to do anyway -- https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#multiple_h1_elements_on_one_page

@agoose77 Is this fine to re(-use) under the same license as Sphinx-doc (BSD)?

@tony this code extract is taken from Sphinx core (apidoc), so whilst I won't add or modify the license in any way, you'd need to follow the Sphinx licensing rules.

@agoose77 Thank you! It looks like the same license as Sphinx, then. That works well! (They are a permissive license so fit the case of people sharing / re-using the code well)

Oh wait, is that a single page with multiple h1s? If so, all the h1s will end up in the left sidebar and there's not much that Furo can do about that -- Sphinx's toctree context variable adds every h1 to the toctree HTML in that manner, with no real metadata to allow Furo to trim things. See pradyunsg.me/furo/kitchen-sink/structure/#structural-elements-2 for example.

Besides, restricting pages to have a single h1 is the right thing to do anyway -- developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#multiple_h1_elements_on_one_page

Yes. It's a little confusing that the left sidebar is H1 and the right sidebar is H(n > 1). I would expect it to be left sidebar = pages, right sidebar = headings.

I guess it's expecting H1 to equal "page", and that makes sense since that's the only way a page gets its name. It would be nice if there were tooling to enforce one H1 per page, though. Part of the problem is the way headings work in RST. I've noticed other instances of incorrect headings which were never noticed. Furo's right sidebar makes it much easier to see what is going on with the heading levels.

There's reasonable Markdown linting tooling though, which combined with MyST-Parser would make it relatively straightforward to enforce. :)

AFAIK, the only rough edge with that is API docs, and even those aren't that painful.

I found another interesting thing here. When using automodule with :members:, if the module docstring has headers in it, then the members of that module are placed under the last header. This is done in the docutils node structure. I don't know if it is intentional or not. It's rather unfortunate for this extension since typically the module docstrings are written to be independent docstrings from the function docstrings, not as a heading for them.

I'm unsure if I should try to work around this in this extension. It's possible this is an autodoc bug because no one ever noticed the structure of the nodes, in which case it ought to be fixed upstream.

I figured out what is going on with automodule, if anyone is interested. It's a bug in the way Sphinx handles module docstrings, and as far as I can tell it's impossible to work around it in this extension. sphinx-doc/sphinx#10804

Adding a cross-reference to sphinx-doc/sphinx#10807 which is a PR to Sphinx, that... I'll go with "drew inspiration from" this Gist. :)

TBF this gist ... drew inspiration from the source in Sphinx ;) I just repackaged it.

This is baked into sphinx 5.2

Settings options:

• add_function_parentheses = False (default: True)
• toc_object_entries_show_parents can be (default: 'domain'):
  • toc_object_entries_show_parents = 'domain'
  • toc_object_entries_show_parents = 'hide'
  • toc_object_entries_show_parents = 'all'

Example w/ Furo theme (screenshot)

My setting:

toc_object_entries_show_parents = 'hide'

URL: https://libvcs.git-pull.com/sync/git.html (may break in future, sorry!)