Description
Describe the bug
From Sphinx docs:
The “root document” (selected by root_doc) is the “root” of the TOC tree hierarchy.
It appears that the ultimate root for any toctree is "hardcoded" as the master_doc
in global toctree resolution and this master_doc
also replaces any orphaned root, i.e any ancestor chain is generated like:
master_doc <- ... <- ...
Note that _get_toctree_ancestors
returns the nodes excluding the root ancestor for that path. However global_toctree_for_doc
seems to collect toctree nodes from env.master_doctree
.
This behavior seems like a bug since for documents included in the orphaned tree but not in master_doc
, the sidebar navigation tree on that html document page still shows the toctree for master_doc
and is unable to expand to the current document.
How to Reproduce
Toctree Graph
index orphan_root
\ / \
\ / \
alpha bravo
/ /
delta charlie
Files
index.rst
index
======
.. toctree::
alpha
alpha.rst
alpha
======
.. toctree::
delta
delta.rst
delta
====
orphan_root.rst
orphan_root
===========
.. toctree::
alpha
bravo
bravo.rst
bravo
=====
.. toctree::
charlie
charlie.rst
charlie
=======
conf.py
Build
sphinx-build -b html . _build
Behavior
-
alpha.rst: document is referenced in multiple toctrees: ['index', 'orphan_root'], selecting: orphan_root <- alpha
is logged which is inconsistent because of the hardcoded behvaior the path would becomeindex <- alpha
. This can also been seen inalpha.html
navigation sidebar where the toctree fromindex
expanded toalpha
and the siblings which are exclusive child ofoprhan_root
i.e['bravo']
are not present in the sidebar. -
In
charlie.html
the navigation sidebar shows the toctree fromindex
unable to be expanded tocharlie
this is likely because the path:index <- bravo <- charlie
is invalid.
Expected Behavior
- Logging should be consistent with global toctree resolution behavior.
- Ideally, in
charlie.html
the global toctree should have been resolved starting fromorphan_root
.
Environment Information
Platform: linux; (Linux-5.15.153.1-microsoft-standard-WSL2-x86_64-with-glibc2.35)
Python version: 3.10.12 (main, Sep 11 2024, 15:47:36) [GCC 11.4.0])
Python implementation: CPython
Sphinx version: 8.1.1
Docutils version: 0.21.2
Jinja2 version: 3.1.4
Pygments version: 2.18.0
Sphinx extensions
No response
Additional context
Relates to: