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 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.

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:

• Ensure deterministic resolution of toctree #12888
• #1090926