✨ NEW: Add tableofcontents directive (#11)

This is a re-working of jupyter-book/jupyter-book#757
(by @choldgraf and @AakashGfude),
but improved since the replacement is made in the `doctree-read` phase
(rather than a post transform)
and so does not have to deal with any builder specific logic.
Also better warnings and testing 😉 

Note, the current implementation does not wrap the toctrees in
`compound(classes=["tableofcontents-wrapper"])`, like in jupyter-book,
but I feel this is unnecessary.

Author: chrisjsewell

.pre-commit-config.yaml

@@ -4,6 +4,7 @@
 exclude: >
     (?x)^(
       \.vscode/settings\.json|
+      tests/.*xml|
     )$
 
 repos:

README.md

@@ -114,6 +114,11 @@ main:
 
 You can also **limit the TOC numbering depth** by setting the `numbered` flag to an integer instead of `true`, e.g., `numbered: 3`.
 
+:::{note}
+By default, section numbering restarts for each `part`.
+If you want want this numbering to be continuous, check-out the [sphinx-multitoc-numbering extension](https://github.com/executablebooks/sphinx-multitoc-numbering).
+:::
+
 ### Defaults
 
 To have e.g. `numbered` added to all toctrees, set it under a `defaults` top-level key:
@@ -132,6 +137,26 @@ main:
 
 Available keys: `numbered`, `titlesonly`, `reversed`
 
+## Add a ToC to a page's content
+
+By default, the `toctree` generated per document (one per `part`) are appended to the end of the document and hidden (then, for example, most HTML themes show them in a side-bar).
+But if you would like them to be visible at a certain place within the document body, you may do so by using the `tableofcontents` directive:
+
+ReStructuredText:
+
+```restructuredtext
+.. tableofcontents::
+```
+
+MyST Markdown:
+
+````md
+```{tableofcontents}
+```
+````
+
+Currently, only one `tableofcontents` should be used per page (all `toctree` will be added here), and only if it is a page with child/descendant documents.
+
 ## Excluding files not in ToC
 
 By default, Sphinx will build all document files, regardless of whether they are specified in the Table of Contents, if they:
@@ -241,7 +266,7 @@ Questions / TODOs:
   it will add `doc.rst` to the excluded patterns but then, when looking for `doc.md`,
   will still select `doc.rst` (since it is first in `source_suffix`).
   Maybe open an issue on sphinx, that `doc2path` should respect exclude patterns.
-
+- Intergrate https://github.com/executablebooks/sphinx-multitoc-numbering into this extension? (or upstream PR)
 
 [github-ci]: https://github.com/executablebooks/sphinx-external-toc/workflows/continuous-integration/badge.svg?branch=main
 [github-link]: https://github.com/executablebooks/sphinx-external-toc

docs/_toc.yml

@@ -4,11 +4,13 @@ defaults:
 main:
   file: intro
   title: Introduction
-  sections:
-  - file: doc1
-  - file: doc2
-    sections:
-    - file: subfolder/doc3
-    - url: https://example.com
-      title: Example Link
-  - glob: subglobs/glob*
+  parts:
+  - sections:
+    - file: doc1
+    - file: doc2
+      sections:
+      - file: subfolder/doc3
+      - url: https://example.com
+        title: Example Link
+  - sections:
+    - glob: subglobs/glob*

docs/intro.md

@@ -1,7 +1,10 @@
 # sphinx-external-toc [IN-DEVELOPMENT]
 
-A sphinx extension that allows the documentation toctree to be defined in a single file.
+A sphinx extension that allows the documentation toctree to be defined in a single YAML file.
 
 In normal Sphinx documentation, the documentation structure is defined *via* a bottom-up approach - adding [`toctree` directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents) within pages of the documentation.
 
 This extension facilitates a **top-down** approach to defining the structure, within a single file that is external to the documentation.
+
+```{tableofcontents}
+```

sphinx_external_toc/__init__.py

@@ -11,7 +11,12 @@
 
 def setup(app: "Sphinx") -> dict:
     """Initialize the Sphinx extension."""
-    from .events import add_changed_toctrees, append_toctrees, parse_toc_to_env
+    from .events import (
+        add_changed_toctrees,
+        insert_toctrees,
+        parse_toc_to_env,
+        TableofContents,
+    )
 
     # variables
     app.add_config_value("external_toc_path", "_toc.yml", "env")
@@ -22,7 +27,8 @@ def setup(app: "Sphinx") -> dict:
     # it will always mark the config as changed in the env setup and re-build everything
     app.connect("config-inited", parse_toc_to_env, priority=900)
     app.connect("env-get-outdated", add_changed_toctrees)
+    app.add_directive("tableofcontents", TableofContents)
     # Note: this needs to occur before `TocTreeCollector.process_doc` (default priority 500)
-    app.connect("doctree-read", append_toctrees, priority=100)
+    app.connect("doctree-read", insert_toctrees, priority=100)
 
     return {"version": __version__, "parallel_read_safe": True}

sphinx_external_toc/events.py

@@ -1,7 +1,7 @@
-"""Sphinx event functions."""
+"""Sphinx event functions and directives."""
 import glob
 from pathlib import Path
-from typing import List, Optional, Set
+from typing import Any, List, Optional, Set
 
 from docutils import nodes
 from sphinx.addnodes import toctree as toctree_node
@@ -10,6 +10,7 @@
 from sphinx.environment import BuildEnvironment
 from sphinx.errors import ExtensionError
 from sphinx.util import docname_join, logging
+from sphinx.util.docutils import SphinxDirective
 from sphinx.util.matching import Matcher, patfilter, patmatch
 
 from .api import DocItem, GlobItem, FileItem, SiteMap, UrlItem, parse_toc_file
@@ -48,7 +49,6 @@ def parse_toc_to_env(app: Sphinx, config: Config) -> None:
 
     Also, change the ``master_doc`` and add to ``exclude_patterns`` if necessary.
     """
-    print(config["exclude_patterns"])
     try:
         site_map = parse_toc_file(Path(app.srcdir) / app.config["external_toc_path"])
     except Exception as exc:
@@ -118,7 +118,21 @@ def add_changed_toctrees(
     return changed_docs
 
 
-def append_toctrees(app: Sphinx, doctree: nodes.document) -> None:
+class TableOfContentsNode(nodes.Element):
+    """A placeholder for the insertion of a toctree (in ``append_toctrees``)."""
+
+    def __init__(self, **attributes: Any) -> None:
+        super().__init__(rawsource="", **attributes)
+
+
+class TableofContents(SphinxDirective):
+    # TODO allow for name option of tableofcontents (to reference it)
+    def run(self) -> List[TableOfContentsNode]:
+        """Insert a ``TableOfContentsNode`` node."""
+        return [TableOfContentsNode()]
+
+
+def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
     """Create the toctree nodes and add it to the document.
 
     Adapted from `sphinx/directives/other.py::TocTree`
@@ -133,18 +147,44 @@ def append_toctrees(app: Sphinx, doctree: nodes.document) -> None:
             line=node.line,
         )
 
+    toc_placeholders: List[TableOfContentsNode] = list(
+        doctree.traverse(TableOfContentsNode)
+    )
+
     site_map: SiteMap = app.env.external_site_map
     doc_item: Optional[DocItem] = site_map.get(app.env.docname)
 
     if doc_item is None or not doc_item.parts:
+        if toc_placeholders:
+            create_warning(
+                app,
+                doctree,
+                "tableofcontents",
+                "tableofcontents directive in document with no descendants",
+            )
+        for node in toc_placeholders:
+            node.replace_self([])
         return
 
+    # TODO allow for more than one tableofcontents, i.e. per part?
+    for node in toc_placeholders[1:]:
+        create_warning(
+            app,
+            doctree,
+            "tableofcontents",
+            "more than one tableofcontents directive in document",
+            line=node.line,
+        )
+        node.replace_self([])
+
     # initial variables
     suffixes = app.config.source_suffix
     all_docnames = app.env.found_docs.copy()
     all_docnames.remove(app.env.docname)  # remove current document
     excluded = Matcher(app.config.exclude_patterns)
 
+    node_list: List[nodes.Element] = []
+
     for toctree in doc_item.parts:
 
         subnode = toctree_node()
@@ -158,15 +198,13 @@ def append_toctrees(app: Sphinx, doctree: nodes.document) -> None:
         # but alabaster theme intermittently raised `KeyError('rawcaption')`
         subnode["rawcaption"] = toctree.caption or ""
         subnode["glob"] = any(isinstance(entry, GlobItem) for entry in toctree.sections)
-        subnode["hidden"] = True
+        subnode["hidden"] = False if toc_placeholders else True
         subnode["includehidden"] = False
         subnode["numbered"] = toctree.numbered
         subnode["titlesonly"] = toctree.titlesonly
         wrappernode = nodes.compound(classes=["toctree-wrapper"])
         wrappernode.append(subnode)
 
-        node_list: List[nodes.Element] = []
-
         for entry in toctree.sections:
 
             if isinstance(entry, UrlItem):
@@ -217,7 +255,10 @@ def append_toctrees(app: Sphinx, doctree: nodes.document) -> None:
 
         node_list.append(wrappernode)
 
-        # note here the toctree cannot not just be appended to the end of the document,
+    if toc_placeholders:
+        toc_placeholders[0].replace_self(node_list)
+    else:
+        # note here the toctree cannot not just be appended to the end of the doc,
         # since `TocTreeCollector.process_doc` expects it in a section
         # TODO check if there is this is always ok
         doctree.children[-1].extend(node_list)

tests/_toc_files/basic.yml

@@ -13,3 +13,5 @@ main:
         - sections:
           - file: subfolder/doc4
           - url: https://example.com
+meta:
+  regress: intro

tests/_toc_files/basic_compressed.yml

@@ -10,3 +10,5 @@ main:
     sections:
     - file: doc4
     - url: https://example.com
+meta:
+  regress: intro

tests/_toc_files/tableofcontents.yml

@@ -0,0 +1,12 @@
+main:
+  file: intro
+  parts:
+  - sections:
+    - file: doc1
+  - sections:
+    - file: doc2
+meta:
+  create_append:
+    intro: |
+      .. tableofcontents::
+  regress: intro

tests/_warning_toc_files/multiple_tableofcontents.yml

@@ -0,0 +1,11 @@
+main:
+  file: intro
+  sections:
+  - file: doc1
+meta:
+  create_append:
+    intro: |
+      .. tableofcontents::
+
+      .. tableofcontents::
+  expected_warning: more than one tableofcontents directive