Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Inconsistent global toctree resolution for nodes in orphaned tree #13012

Open
khanxmetu opened this issue Oct 12, 2024 · 0 comments
Open

Inconsistent global toctree resolution for nodes in orphaned tree #13012

khanxmetu opened this issue Oct 12, 2024 · 0 comments

Comments

@khanxmetu
Copy link
Contributor

khanxmetu commented Oct 12, 2024

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:

@khanxmetu 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants