sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.61k stars 2.13k forks source link

Inconsistent global toctree resolution for nodes in orphaned tree #13012

Open khanxmetu opened 1 month ago

khanxmetu commented 1 month ago

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

Expected Behavior

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: