HTML is overwritten but Builder.get_outdated_docs doesn't say it would

[felix-hilden]

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:

   another

Another
-------

• 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-codeautolink

Additional context

No response

[AA-Turner]

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]

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]

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.