[app] Allow extensions to detect freshenv builds (#12358)

Some extensions cache data outside of the `BuildEnvironment` (usually for memory/performance reasons).
For these extensions, it would be helpful to detect when `sphinx-build -E` has been called, which in essence suggests the user wishes to remove cached data before building.

This commit adds the `Sphinx.fresh_env_used` public property, exposing `Sphinx._fresh_env_used` in an immutable manner.

Author: chrisjsewell

sphinx/application.py

@@ -143,8 +143,30 @@ def __init__(self, srcdir: str | os.PathLike[str], confdir: str | os.PathLike[st
                  tags: list[str] | None = None,
                  verbosity: int = 0, parallel: int = 0, keep_going: bool = False,
                  pdb: bool = False) -> None:
+        """Initialize the Sphinx application.
+
+        :param srcdir: The path to the source directory.
+        :param confdir: The path to the configuration directory.
+            If not given, it is assumed to be the same as ``srcdir``.
+        :param outdir: Directory for storing build documents.
+        :param doctreedir: Directory for caching pickled doctrees.
+        :param buildername: The name of the builder to use.
+        :param confoverrides: A dictionary of configuration settings that override the
+            settings in the configuration file.
+        :param status: A file-like object to write status messages to.
+        :param warning: A file-like object to write warnings to.
+        :param freshenv: If true, clear the cached environment.
+        :param warningiserror: If true, warnings become errors.
+        :param tags: A list of tags to apply.
+        :param verbosity: The verbosity level.
+        :param parallel: The maximum number of parallel jobs to use
+            when reading/writing documents.
+        :param keep_going: If true, continue processing when an error occurs.
+        :param pdb: If true, enable the Python debugger on an exception.
+        """
         self.phase = BuildPhase.INITIALIZATION
         self.verbosity = verbosity
+        self._fresh_env_used: bool | None = None
         self.extensions: dict[str, Extension] = {}
         self.registry = SphinxComponentRegistry()
 
@@ -267,6 +289,13 @@ def __init__(self, srcdir: str | os.PathLike[str], confdir: str | os.PathLike[st
         # set up the builder
         self._init_builder()
 
+    @property
+    def fresh_env_used(self) -> bool | None:
+        """True/False as to whether a new environment was created for this build,
+        or None if the environment has not been initialised yet.
+        """
+        return self._fresh_env_used
+
     def _init_i18n(self) -> None:
         """Load translated strings from the configured localedirs if enabled in
         the configuration.
@@ -319,7 +348,6 @@ def _load_existing_env(self, filename: str) -> BuildEnvironment:
     def _post_init_env(self) -> None:
         if self._fresh_env_used:
             self.env.find_files(self.config, self.builder)
-        del self._fresh_env_used
 
     def preload_builder(self, name: str) -> None:
         self.registry.preload_builder(self, name)