[follow-up] Generating <title> in HTML builds.

[picnixz]

This is a follow-up of #11705.

In order to generate the content of the <title> element for each document, Sphinx saves instances of docutils.nodes.title in the environment and uses them during the writing phase. More precisely, for each document, we either extract the content of :title: or the title of the first section. Then, during the writing phase, we render it by creating a fake document.

In both cases, what is stored is a docutils.nodes.title element which will not be transformed by Sphinx transformations (or post-transformations). In particular, when the fake document is translated into HTML, it may lack information added by those transformations. If a visitor method expects a node to be transformed by Sphinx transformations or post-transformations, then it would not work for partial documents.

A simple workaround (that I implemented in #11705) is to detect whether the document being processed is partial or not and apply the visitor if it is not. This however requires to know in advance which transformation is here or not. In particular, some extensions may need a more careful check for that.

The tasks to address are the following:

• Check that all partial documents are detected correctly during the writing phase and that the information stored in those partial documents is sufficient.
• Change the way that titles are stored in the environment, either by keeping a real reference to them (i.e., the node being stored is automatically transformed by the transformation or post-transformation since they are modifying the document in-place) or by applying the transformations and post-transformations to them when they are used in a partial documents. Note that applying transformations and post-transformations to partial documents may be tricky because these are created during the writing phase and not the build phase IIRC.

Details concerning <title>

I am only aware of using partial documents to render the <title> element. Currently, if we have a doctree whose first <section> element (detected as the title of the document) contains a node that could be transformed as well and whose transformation adds information needed by the translator (e.g., a <manpage> node as of 7.2.6), the title being stored will contain that manpage node. However, during the translation phase, we will first render the <title> using a fake document and apply the translator on that specific document. Upon encountering the <manpage>, it tries to format manpages_url but since the manpage transformation was never applied to that node, the latter lacks the required formatting arguments, leading to #11673.

cc @AA-Turner