sphinx-structured-toc 0.1.0__tar.gz → 0.2.0__tar.gz

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/.readthedocs.yaml

@@ -12,14 +12,18 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py
+
+# Also build a PDF, using Read the Docs' LaTeX toolchain
+formats:
+  - pdf
 
 # Install the project with the `docs` extra so the `furo` theme is
 # available during the docs build.
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
-   install:
-   - method: pip
-     path: .
-     extra_requirements:
-       - docs
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-structured-toc
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Sphinx extension for rendering compact, semantic, accessible documentation link lists grouped by domain.
 Author: Daniele Procida
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -678,6 +678,9 @@ License:                     GNU GENERAL PUBLIC LICENSE
         Public License instead of this License.  But first, please read
         <https://www.gnu.org/licenses/why-not-lgpl.html>.
         
+Project-URL: Documentation, https://canonical-sphinx-structured-toc.readthedocs-hosted.com/
+Project-URL: Source, https://github.com/canonical/sphinx-structured-toc
+Project-URL: Issues, https://github.com/canonical/sphinx-structured-toc/issues
 Keywords: sphinx,accessibility,toc,aria
 Classifier: Framework :: Sphinx :: Extension
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
@@ -694,6 +697,7 @@ Requires-Dist: docutils>=0.21.2
 Requires-Dist: sphinx~=7.0
 Provides-Extra: docs
 Requires-Dist: furo>=2024.1.29; extra == "docs"
+Requires-Dist: sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1; extra == "docs"
 Dynamic: license-file
 
 Sphinx structured table of contents

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/common.mk

@@ -24,28 +24,28 @@ export UV_FROZEN := true
 
 .PHONY: help
 help: ## Show this help.
-@printf "\e[1m%-30s\e[0m | \e[1m%s\e[0m\n" "Target" "Description"
-printf "\e[2m%-30s + %-41s\e[0m\n" "------------------------------" "------------------------------------------------"
-egrep '^[^:]+\: [^#]*##' $$(echo $(MAKEFILE_LIST) | tac --separator=' ') | sed -e 's/^[^:]*://' -e 's/:[^#]*/ /' | sort -V| awk -F '[: ]*' \
-'{
-if ($$2 == "##")
-{
-$$1=sprintf(" %-28s", $$1);
-$$2=" | ";
-print $$0;
-}
-else
-{
-$$1= %-25s", $$1);sprintf("  
-$$2=" | ";
-$$3= %s", $$3);sprintf(" 
-print $$0;
-}
-}'
+	@printf "\e[1m%-30s\e[0m | \e[1m%s\e[0m\n" "Target" "Description"
+	printf "\e[2m%-30s + %-41s\e[0m\n" "------------------------------" "------------------------------------------------"
+	egrep '^[^:]+\: [^#]*##' $$(echo $(MAKEFILE_LIST) | tac --separator=' ') | sed -e 's/^[^:]*://' -e 's/:[^#]*/ /' | sort -V| awk -F '[: ]*' \
+	'{
+	if ($$2 == "##")
+	{
+	$$1=sprintf(" %-28s", $$1);
+	$$2=" | ";
+	print $$0;
+	}
+	else
+	{
+	$$1=sprintf(" %-25s", $$1);
+	$$2=" | ";
+	$$3=sprintf(" %s", $$3);
+	print $$0;
+	}
+	}'
 
 .PHONY: install
 install: install-uv install-linters install-precommit install-build-deps ## Set up a development environment
-uv sync $(UV_TEST_GROUPS) $(UV_LINT_GROUPS)
+	uv sync $(UV_TEST_GROUPS) $(UV_LINT_GROUPS)
 
 .PHONY: install-linters
 install-linters: install-uv install-shellcheck install-pyright install-lint-build-deps
@@ -53,213 +53,213 @@ install-linters: install-uv install-shellcheck install-pyright install-lint-buil
 .PHONY: install-precommit
 install-precommit: install-uv  ##- Set up pre-commit hooks in this repository.
 ifeq ($(shell which pre-commit),)
-uv tool run pre-commit install
+	uv tool run pre-commit install
 else
-pre-commit install
+	pre-commit install
 endif
 
 .PHONY: clean
 clean:  ## Clean up the development environment
-uv tool run pyclean .
-rm -rf dist/ build/ .test_output/ .coverage*
+	uv tool run pyclean .
+	rm -rf dist/ build/ .test_output/ .coverage*
 
 .PHONY: autoformat
 autoformat: format  # Hidden alias for 'format'
 
 .PHONY: format-ruff
 format-ruff: install-ruff  ##- Automatically format with ruff
-success=true
-ruff check --fix $(SOURCES) || success=false
-ruff format $(SOURCES)
-$$success || exit 1
+	success=true
+	ruff check --fix $(SOURCES) || success=false
+	ruff format $(SOURCES)
+	$$success || exit 1
 
 .PHONY: format-codespell
 format-codespell:  ##- Fix spelling issues with codespell
-uv run codespell --toml pyproject.toml --write-changes $(SOURCES)
+	uv run codespell --toml pyproject.toml --write-changes $(SOURCES)
 
 .PHONY: format-prettier
 format-prettier: install-npm  ##- Format files with prettier
-$(PRETTIER) --write $(PRETTIER_FILES)
+	$(PRETTIER) --write $(PRETTIER_FILES)
 
 .PHONY: setup-tests
 setup-tests: install-uv install-build-deps ##- Set up a testing environment without linters
-uv sync $(UV_TEST_GROUPS)
+	uv sync $(UV_TEST_GROUPS)
 
 .PHONY: setup-lint
 setup-lint: install-uv install-shellcheck install-pyright install-lint-build-deps  ##- Set up a linting-only environment
-uv sync $(UV_LINT_GROUPS)
+	uv sync $(UV_LINT_GROUPS)
 
 .PHONY: lint-ruff
 lint-ruff: install-ruff  ##- Lint with ruff
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
-ruff check $(SOURCES)
-ruff format --diff $(SOURCES)
+	ruff check $(SOURCES)
+	ruff format --diff $(SOURCES)
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: lint-codespell
 lint-codespell: install-codespell  ##- Check spelling with codespell
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
-uv run codespell --toml pyproject.toml $(SOURCES)
+	uv run codespell --toml pyproject.toml $(SOURCES)
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: lint-mypy
 lint-mypy:  ##- Check types with mypy
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
-uv run mypy --show-traceback --show-error-codes $(PROJECT)
+	uv run mypy --show-traceback --show-error-codes $(PROJECT)
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: lint-pyright
 lint-pyright:  ##- Check types with pyright
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
 ifneq ($(shell which pyright),)
-pyright --pythonpath .venv/bin/python
+	pyright --pythonpath .venv/bin/python
 else
-uv tool run pyright --pythonpath .venv/bin/python
+	uv tool run pyright --pythonpath .venv/bin/python
 endif
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: lint-shellcheck
 lint-shellcheck:  ##- Lint shell scripts
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
-git ls-files | file --mime-type -Nnf- | grep shellscript | cut -f1 -d: | xargs -r shellcheck
+	git ls-files | file --mime-type -Nnf- | grep shellscript | cut -f1 -d: | xargs -r shellcheck
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: lint-prettier
 lint-prettier: install-npm  ##- Lint files with prettier
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
-$(PRETTIER) --check $(PRETTIER_FILES)
+	$(PRETTIER) --check $(PRETTIER_FILES)
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: lint-twine
 lint-twine: pack-pip  ##- Lint Python packages with twine
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
-uv tool run twine check dist/*
+	uv tool run twine check dist/*
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: test
 test:  ## Run all tests
-uv run pytest
+	uv run pytest
 
 .PHONY: test-fast
 test-fast:  ##- Run fast tests
-uv run pytest -m 'not slow'
+	uv run pytest -m 'not slow'
 
 .PHONY: test-slow
 test-slow:  ##- Run slow tests
-uv run pytest -m 'slow'
+	uv run pytest -m 'slow'
 
 .PHONY: test-coverage
 test-coverage:  ## Generate coverage report
-uv run coverage run --source $(PROJECT) -m pytest
-uv run coverage xml -o coverage.xml
-uv run coverage report -m
-uv run coverage html
+	uv run coverage run --source $(PROJECT) -m pytest
+	uv run coverage xml -o coverage.xml
+	uv run coverage report -m
+	uv run coverage html
 
 .PHONY: test-find-slow
 test-find-slow:  ##- Identify slow tests. Set cutoff time in seconds with SLOW_CUTOFF_TIME
-uv run pytest --durations 0 --durations-min $(SLOW_CUTOFF_TIME)
+	uv run pytest --durations 0 --durations-min $(SLOW_CUTOFF_TIME)
 
 .PHONY: pack-pip
 pack-pip:  ##- Build packages for pip (sdist, wheel)
 ifneq ($(CI),)
-@echo ::group::$@
+	@echo ::group::$@
 endif
-uv build --quiet .
+	uv build --quiet .
 ifneq ($(CI),)
-@echo ::endgroup::
+	@echo ::endgroup::
 endif
 
 .PHONY: install-uv
 install-uv:
 ifneq ($(shell which uv),)
 else ifneq ($(shell which snap),)
-sudo snap install --classic astral-uv
+	sudo snap install --classic astral-uv
 else ifneq ($(shell which brew),)
-brew install uv
+	brew install uv
 else ifeq ($(OS),Windows_NT)
-pwsh -c "irm https://astral.sh/uv/install.ps1 | iex"
+	pwsh -c "irm https://astral.sh/uv/install.ps1 | iex"
 else
-curl -LsSf https://astral.sh/uv/install.sh | sh
+	curl -LsSf https://astral.sh/uv/install.sh | sh
 endif
 
 .PHONY: install-codespell
 install-codespell:
 ifneq ($(shell which codespell),)
 else ifneq ($(shell which snap),)
-sudo snap install codespell
+	sudo snap install codespell
 else ifneq ($(shell which brew),)
-make install-uv
-uv tool install codespell
+	make install-uv
+	uv tool install codespell
 else
-$(warning Codespell not installed. Please install it yourself.)
+	$(warning Codespell not installed. Please install it yourself.)
 endif
 
 .PHONY: install-pyright
 install-pyright: install-uv
 ifneq ($(shell which pyright),)
 else ifneq ($(shell which snap),)
-sudo snap install --classic pyright
+	sudo snap install --classic pyright
 else
-[ -d "$(HOME)/.npm/_cacache" ] && chown -R `id -u`:`id -g` "$(HOME)/.npm" || true
-uv tool install pyright
+	[ -d "$(HOME)/.npm/_cacache" ] && chown -R `id -u`:`id -g` "$(HOME)/.npm" || true
+	uv tool install pyright
 endif
 
 .PHONY: install-ruff
 install-ruff:
 ifneq ($(shell which ruff),)
 else ifneq ($(shell which snap),)
-sudo snap install ruff
+	sudo snap install ruff
 else
-make install-uv
-uv tool install ruff
+	make install-uv
+	uv tool install ruff
 endif
 
 .PHONY: install-shellcheck
 install-shellcheck:
 ifneq ($(shell which shellcheck),)
 else ifneq ($(shell which snap),)
-sudo snap install shellcheck
+	sudo snap install shellcheck
 else ifneq ($(shell which brew),)
-brew install shellcheck
+	brew install shellcheck
 else
-$(warning Shellcheck not installed. Please install it yourself.)
+	$(warning Shellcheck not installed. Please install it yourself.)
 endif
 
 .PHONY: install-npm
 install-npm:
 ifneq ($(shell which npm),)
 else ifneq ($(shell which snap),)
-sudo snap install --classic node
+	sudo snap install --classic node
 else ifneq ($(shell which brew),)
-brew install node
+	brew install node
 else
-$(error npm not installed. Please install it yourself.)
+	$(error npm not installed. Please install it yourself.)
 endif

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/docs/Makefile

@@ -12,7 +12,7 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile livehtml
+.PHONY: help Makefile livehtml pdf
 
 # Catch-all target: route all unknown targets through Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
@@ -21,3 +21,12 @@ help:
 
 run:
 	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+# Build a PDF with the standard LaTeX toolchain (latexmk + xelatex, as used
+# by the sphinx-docs-starter-pack). The finished PDF is moved to $(BUILDDIR).
+# `-Q` quiets Sphinx; LATEXMKOPTS quiets the latexmk/xelatex passes (it
+# propagates via the environment to the Makefile that `-M latexpdf` runs).
+pdf:
+	@LATEXMKOPTS=-silent $(SPHINXBUILD) -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -Q $(O)
+	@find "$(BUILDDIR)/latex" -name '*.pdf' -exec mv {} "$(BUILDDIR)"/ \;
+	@echo "Output can be found in ./$(BUILDDIR)"

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/docs/conf.py

@@ -11,7 +11,11 @@ sys.path.insert(0, str(project_root))
 project = "sphinx-structured-toc"
 author = "sphinx-structured-toc contributors"
 
-extensions = ["sphinx_structured_toc"]
+extensions = [
+    "sphinx_structured_toc",
+    # Convert SVG images to PDF for LaTeX/PDF output
+    "sphinxcontrib.cairosvgconverter",
+]
 
 html_theme = "furo"
 html_title = project

sphinx_structured_toc-0.2.0/docs/demo-targets/model-reference.rst

@@ -0,0 +1,19 @@
+:orphan:
+
+Model reference
+===============
+
+This page exists as a target for the ``domain`` demonstration.
+
+The example below is just a handly place to keep an example of the directive for use elsewhere in this documentation.
+
+The model layer
+...............
+
+..  domain:: Model layer
+
+    ..  slice:: Models
+
+        :doc:`Introduction </demo-targets/field-types-reference>` domain
+        :doc:`Reference </demo-targets/model-reference>` slice
+        :doc:`Custom fields </demo-targets/custom-fields-how-to>`

sphinx_structured_toc-0.2.0/docs/developer-set-up.rst

@@ -0,0 +1,24 @@
+Development set-up
+======================
+
+Having cloned the repository, build with ``make install`` (at the root; there's a completely unrelated ``Makefile`` for the ``docs`` directory).
+
+``make setup-tests`` is a lighter-weight alternative if you want to run tests but need less of the tooling.
+
+There's some complexity in this; it will opt for ``homebrew`` or ``apt`` to install components.
+
+
+Testing
+-------
+
+``make test`` runs ``uv run pytest``. There's a slow test that can be skipped: ``make test-fast``.
+
+Use ``make test`` to run rests, and ``make test-coverage`` for a coverage report.
+
+
+Running the documentation
+-------------------------
+
+In ``docs``: ``make run`` to launch the documentation site on port 8000.
+
+Changes to the extension code will be picked up live.

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/docs/index.rst

@@ -156,6 +156,7 @@ The view layer
 
     Home <self>
     installation-and-usage
+    developer-set-up
     reference
     developer-reference
     approaches

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/docs/reference.rst

@@ -1,6 +1,8 @@
 Reference
 =============
 
+The extension can only apply ARIA attributes to HTML output. For PDF,  links are generated but without any additional context.
+
 Basic rendering
 ---------------
 
@@ -39,6 +41,69 @@ The example above renders as:
 The ``id``\s are automatically generated as required.
 
 
+ARIA labelling
+--------------
+
+Here's an example that includes accessibility labelling via the ``slice`` and ``domain`` options. There are three links in the slice:
+
+* *Introduction* (to the Model layer, via the ``domain`` option)
+* *Reference* (for Models, via the ``slice`` option)
+* *Custom fields*
+
+..  code-block:: rst
+
+    The model layer
+    ...............
+
+    ..  domain::
+
+        ..  slice:: Models
+
+            :doc:`Introduction </demo-targets/field-types-reference>` domain
+            :doc:`Reference </demo-targets/model-reference>` slice
+            :doc:`Custom fields </demo-targets/custom-fields-how-to>`
+
+The HTML output below has been simplified by removing some elements, classes and other attributes.
+
+In the HTML you can see the ``aria-labelledby`` attribute on various items.
+
+The ``id``\s an ``aria-labelledby`` attribute refers to will give a screen reader an accessible name for that element.
+
+For example, there is an ``<a id="the-model-layer-models-reference">`` (the last highlighted link) that is "labelled by" two other ``id``\s: ``the-model-layer-models-reference`` and ``the-model-layer-models``.
+
+You can identify the text associated with those two ``id``\s; the screenreader will find them and render the accessible name *Reference, Models*.
+
+
+..  code-block:: html
+    :emphasize-lines: 1, 2, 5, 9, 10, 16, 17
+
+    <nav aria-labelledby="model-layer-domain">
+      <span id="model-layer-domain">Model layer</span>
+      <ul>
+        <li>
+          <span id="the-model-layer-models">Models</span>:
+          <ul>
+            <li>
+              <a
+                id="the-model-layer-models-introduction"
+                aria-labelledby="the-model-layer-models-introduction model-layer-domain">
+                <span>Introduction</span>
+                </a>
+              </li>
+              <li>
+                <a
+                  id="the-model-layer-models-reference"
+                  aria-labelledby="the-model-layer-models-reference the-model-layer-models">
+                  <span>Reference</span>
+                </a>
+              </li>
+              <li><a>Custom fields</a></li>
+            </ul>
+          </li>
+        </ul>
+      </nav>
+
+
 Explicitly named domains
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/pyproject.toml

@@ -22,9 +22,15 @@ classifiers = [
 ]
 license = { file = "LICENSE" }
 
+[project.urls]
+Documentation = "https://canonical-sphinx-structured-toc.readthedocs-hosted.com/"
+Source = "https://github.com/canonical/sphinx-structured-toc"
+Issues = "https://github.com/canonical/sphinx-structured-toc/issues"
+
 [project.optional-dependencies]
 docs = [
     "furo>=2024.1.29",
+    "sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1",
 ]
 
 [dependency-groups]
@@ -44,6 +50,7 @@ dev = [
     "pytest-cov~=6.0",
     "pytest-mock~=3.12",
     "sphinx-autobuild>=2024.10.3",
+    "sphinxcontrib-svg2pdfconverter[CairoSVG]~=2.1",
     "twine>=6.2.0",
 ]
 
@@ -217,12 +224,18 @@ select = [
 ]
 ignore = [
     "E501",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
     "D105",
     "D107",
     "D203",
     "D213",
     "D215",
     "A003",
+    "A005",
     "SIM117",
     "COM812",
     "ISC001",
@@ -240,6 +253,7 @@ ignore-decorators = [
 
 [tool.ruff.lint.pylint]
 max-args = 8
+max-branches = 16
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**.py" = [
@@ -257,3 +271,6 @@ max-args = 8
     "I001",
     "F401",
 ]
+"docs/conf.py" = [
+    "INP001",
+]

{sphinx_structured_toc-0.1.0 → sphinx_structured_toc-0.2.0}/sphinx_structured_toc/__init__.py

@@ -1,5 +1,8 @@
+"""A Sphinx extension for rendering compact, semantic, accessible documentation link lists grouped by domain."""
+
 from pathlib import Path
 
+from docutils import nodes as docutils_nodes
 from sphinx.application import Sphinx
 from sphinx.util.typing import ExtensionMetadata
 
@@ -8,10 +11,19 @@ from .html import (
     depart_domain,
     depart_slice,
     depart_slice_item,
+    make_reference_visitor,
     visit_domain,
     visit_slice,
     visit_slice_item,
 )
+from .latex import (
+    depart_domain as latex_depart_domain,
+    depart_slice as latex_depart_slice,
+    depart_slice_item as latex_depart_slice_item,
+    visit_domain as latex_visit_domain,
+    visit_slice as latex_visit_slice,
+    visit_slice_item as latex_visit_slice_item,
+)
 from .nodes import Domain, Slice, SliceItem
 from .transforms import resolve_domains
 
@@ -29,12 +41,25 @@ except ImportError:  # pragma: no cover
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
+    """Register the extension's nodes, directives, transforms and static assets."""
     # register various components
 
     # nodes
-    app.add_node(Domain, html=(visit_domain, depart_domain))
-    app.add_node(Slice, html=(visit_slice, depart_slice))
-    app.add_node(SliceItem, html=(visit_slice_item, depart_slice_item))
+    app.add_node(
+        Domain,
+        html=(visit_domain, depart_domain),
+        latex=(latex_visit_domain, latex_depart_domain),
+    )
+    app.add_node(
+        Slice,
+        html=(visit_slice, depart_slice),
+        latex=(latex_visit_slice, latex_depart_slice),
+    )
+    app.add_node(
+        SliceItem,
+        html=(visit_slice_item, depart_slice_item),
+        latex=(latex_visit_slice_item, latex_depart_slice_item),
+    )
 
     # directives
     app.add_directive("domain", DomainDirective)
@@ -60,18 +85,12 @@ def setup(app: Sphinx) -> ExtensionMetadata:
 
 def add_static_dir(app: Sphinx) -> None:
     """Add the extension package directory to ``html_static_path``."""
-
     if _CSS_DIR not in app.config.html_static_path:
         app.config.html_static_path.append(_CSS_DIR)
 
 
 def install_reference_override(app: Sphinx) -> None:
     """Override ``docutils.nodes.reference`` HTML visitors."""
-
-    from docutils import nodes as docutils_nodes
-
-    from .html import make_reference_visitor
-
     visit, depart = make_reference_visitor(app)
     app.add_node(
         docutils_nodes.reference,