You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
khanxmetu
changed the title
Inconsistent global toctree resolution for nodes exclusive in orphaned tree
Inconsistent global toctree resolution for nodes in orphaned tree
Oct 12, 2024
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
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
charlie.html
the global toctree should have been resolved starting fromorphan_root
.Environment Information
Sphinx extensions
No response
Additional context
Relates to:
The text was updated successfully, but these errors were encountered: