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 become index <- alpha. This can also been seen in alpha.html navigation sidebar where the toctree from index expanded to alpha and the siblings which are exclusive child of oprhan_root i.e ['bravo'] are not present in the sidebar.
In charlie.html the navigation sidebar shows the toctree from index unable to be expanded to charlie 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 from orphan_root.
Describe the bug
From Sphinx docs:
It appears that the ultimate root for any toctree is "hardcoded" as the
master_doc
in global toctree resolution and thismaster_doc
also replaces any orphaned root, i.e any ancestor chain is generated like:Note that
_get_toctree_ancestors
returns the nodes excluding the root ancestor for that path. Howeverglobal_toctree_for_doc
seems to collect toctree nodes fromenv.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 formaster_doc
and is unable to expand to the current document.How to Reproduce
Toctree Graph
Files
index.rst
alpha.rst
delta.rst
orphan_root.rst
bravo.rst
charlie.rst
conf.py
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
charlie.html
the global toctree should have been resolved starting fromorphan_root
.Environment Information
Sphinx extensions
No response
Additional context
Relates to:
12888