Sphinx 8.1.0

[AA-Turner]

Sphinx 8.1 has been released and can be found on PyPI.

Sphinx 8.1 is a stable release with several new features and many bug-fixes. See the detailed changelog or the tracking issue for further information.

To install this release, run pip install Sphinx==8.1.0

Should you encounter any issues, please write here or on GitHub issues with further detail.

Adam

[dhalbert]

document is referenced in multiple toctrees:

With 8.1.0, I am now getting multiple lines from the "checking consistency" output, of the form:

/blah/index.rst: document is referenced in multiple toctrees: ['docs/pdf', 'somewhere-else/index'], selecting: somewhere-else/index <-somewhere-else/foo/index

I don't see these messages with 8.0.2 or earlier. I see them whether I'm building html or latex output. In addition, the latex build is failing.

I think this is related to the latex changes in 8.1.0, because there is a conf.py line like the line below. Note that it refers to docs/pdf. docs/pdf is present in all the document is referenced in multiple toctrees messages I am seeing.

latex_documents = [
  ("docs/pdf", ...),
]

I tried coming up with a simple reproducer, but didn't succeed yet, so I'm reporting here, instead of in an issue. If you want me to open an issue, I'd be happy to. The project in question is https://github.com/adafruit/circuitpython. It has a top-level make html target. The pip requirements for the doc build are in requirements-doc.txt. See conf.py at the top level and docs/.

[AA-Turner]

This is due to #12888. The challenge is that the toctree is designed to be a tree with no multiple inheritance, and hence can cause switching of contexts in the breadcrumbs if not a tree.

In your case it is becuase you have a distinct toctree root in your pdf.rst.

cc @khanxmetu @jayaddison thoughts on this case?

A

[AA-Turner]

@dhalbert for now, the lines are safe to ignore -- they're informational only. We will see if there is something we can do to improve the experience, or suggest changes you can make to your configuration in CircuitPython.

[dhalbert]

Thank you. There is something going on with our latex build which is breaking it, so I had to pin at 8.0.2 anyway. I thought those messages were related, but I see that there are a number of latex changes in 8.1.0 as well, so the messages may be a red herring.

Maybe we don't need two roots, one for html and one for pdf. The pdf build omits some stuff that is very large when converted to PDF, but we had two roots before that anyway.

[khanxmetu]

@AA-Turner While investigating this issue I encountered a strange behavior related to global toctree for nodes in orphaned tree: #13012

Interestingly, if it's safe to leave the sidebar navigation broken/unexpanded for nodes exclusive in orphaned tree and keeping the master_doc hardcoded as the ultimate root for any toctree as it currently is, the fix for the issue described here is relatively easier. With respect to the current behavior of global toctree resolution, the _check_toc_parents should consider only the descendants of master_doc and not the whole graph.

I have opened #13012 just for the record and demonstration, however I think we should prioritize the issue mentioned here instead of fixing the sidebar navigation. Let me know what you think.

[AA-Turner]

Sphinx 8.1.1 has been released with two small bug fixes.

A

[jdknight]

Appears to be an issue with autodoc's autodoc-process-docstring capability (see #13013).