Create a new type for the current document's environment state (#13151)

doc/extdev/envapi.rst

@@ -47,6 +47,52 @@ Build environment API
 
    .. autoattribute:: parser
 
+   **Per-document attributes**
+
+   .. attribute:: current_document
+
+      Temporary data storage while reading a document.
+
+      Extensions may use the mapping interface provided by
+      ``env.current_document`` to store data relating to the current document,
+      but should use a unique prefix to avoid name clashes.
+
+      .. important::
+         Only the following attributes constitute the public API.
+         The type itself and any methods or other attributes remain private,
+         experimental, and will be changed or removed without notice.
+
+      .. attribute:: current_document.docname
+         :type: str
+
+         The document name ('docname') for the current document.
+
+      .. attribute:: current_document.default_role
+         :type: str
+
+         The default role for the current document.
+         Set by the :dudir:`default-role` directive.
+
+      .. attribute:: current_document.default_domain
+         :type: Domain | None
+
+         The default domain for the current document.
+         Set by the :rst:dir:`default-domain` directive.
+
+      .. attribute:: current_document.highlight_language
+         :type: str
+
+         The default language for syntax highlighting.
+         Set by the :rst:dir:`highlight` directive to override
+         the :confval:`highlight_language` config value.
+
+      .. attribute:: current_document._parser
+         :type: Parser | None
+
+         *This attribute is experimental and may be changed without notice.*
+
+         The parser being used to parse the current document.
+
    **Utility methods**
 
    .. automethod:: doc2path