Repository navigation
HTML is overwritten but Builder.get_outdated_docs doesn't say it would #13390
Description
Describe the bug
Hi, I'm the author of sphinx-codeautolink, a package that injects links into code examples in HTML output. We rely on Builder.get_outdated_docs to optimise the processing (which is done in the build-finished event). Since exactly version 7.3.7 Sphinx has started overwriting all the HTML files if there's even one outdated file, leading to a bug in repeat builds.
Curiously, with version 7.3.6 (which works for the extension) if I edit the HTML file manually to e.g. change the title and rebuild, my edit is overwritten too. This leads me to believe that Sphinx is somehow tracking the resulting HTML and overwriting if necessary - and that the checkpoint for that tracking has changed. So if this is not considered a bug, is there a way I can still implement HTML post-processing with awareness for outdated documents?
How to Reproduce
# conf.py
extensions = ["sphinx.ext.intersphinx", "sphinx_codeautolink"]
intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}Title
-----
.. code:: python
import re
re.match()
.. toctree::
:hidden:
anotherAnother
-------- pip install sphinx==7.3.6 sphinx-codeautolink
- sphinx-build src build
- open index.html and see links generated
- edit "another.rst" to e.g. include content under the title and rebuild
- open index.html and see the links are still there
Repeat with sphinx==7.3.7 and the links after the second build are no longer there.
Environment Information
None beyond the sphinx versions mentioned above.
Sphinx extensions
sphinx-codeautolinkAdditional context
No response
Activity
AA-Turner commentedon Feb 24, 2025
Can you provide a mininal reproducer, ideally a tiny extension with just the relevant hook?
These are the commits between 7.3.6 and 7.3.7, which don't seem to change the HTML builder: v7.3.6...v7.3.7
A
felix-hilden commentedon Feb 24, 2025
Woah yeah those are very minimal changes indeed. Could you not reproduce it? It'll take me a bit of time to create something that would "minimally" do things on partial builds and inject HTML. But I'll come back to you 👍
felix-hilden commentedon Feb 25, 2025
I.. actually can't even reproduce it now with my own extension, let alone a minimal one. It seems to be overridden every time all the way down to Sphinx 5. So at this point I'd probably have to say that I've been crazy and/or it might have been my browser caching all along.
I guess then my question is a more general one: can I hook into Sphinx's decision to write individual HTML files? Or should I always do post-processing on all the HTML output no matter what the outdated documents are? Maybe the html-page-context event is relevant, but I'm not sure what the templates mean.