Site Map

The Site Map tree view visualises your project’s navigation tree — the structure built from Sphinx-style toctree directives, starting from the project’s root document ([project].root_doc, index by default).

It is the same expansion Sphinx uses to build the sidebar and the document ordering, computed by the ubCode language server and served to the view ready to render.

Project

The tree leads with a Project row naming the project being shown, which expands to its ubproject.toml and the file the view is following (both open in the editor when clicked).

By default the view follows the active editor. Hover the Project row and use the pin button to lock every ubCode view to that project, and the unpin button to go back to following the editor — the same ubcode.views.pinnedProject setting the other views share, so a project pinned from anywhere is respected here too.

Structure

Below the Project row, the tree is rooted at the root document. Each document’s children are its toctree groups:

  • A toctree with a :caption: becomes an intermediate, collapsible group node labelled with the caption.

  • A toctree without a caption inlines its entries directly under the document.

Every entry is resolved server-side, so the view shows the entry’s display title (the explicit entry title, the target document’s title, or its docname, in that order).

Entry kinds

Each entry is one of three kinds:

  • Documents open the corresponding source file when clicked.

  • External URLs (Label <https://…> entries) open in your browser.

  • Generated pages (genindex, modindex, search) are shown as non-clickable leaves.

Hidden toctrees

A :hidden: toctree is omitted from the rendered documentation sidebar, but it still contributes structure and document ordering. The Site Map is a map of the project, not the rendered navigation, so hidden groups are shown, marked with a hidden label so they are easy to tell apart.

Keeping up to date

The view refreshes automatically after the project is re-indexed, but only when the navigation tree actually changed — editing a need’s body, for example, does not disturb it. Use the refresh button in the view’s title bar to re-index and reload on demand.

If the project defines no toctree directives (or its root document is missing), the view shows a short placeholder instead of a tree.