Close #8081: latex: Allow to add LaTeX package until writing tex file

This postpones the evaluation of LaTeX packages via
``app.add_latex_package()`` to just before writing .tex file.  That
allows extensions to add LaTeX packages during reading and resolving
phase.

4 files changed, 36 insertions, 9 deletions

diff --git a/CHANGES b/CHANGES
index 738baf341..b459af41e 100644
--- a/CHANGES
+++ b/CHANGES
@@ -10,6 +10,9 @@ Incompatible changes
 Deprecated
 ----------
 
+* ``sphinx.builders.latex.LaTeXBuilder.usepackages``
+* ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
+
 Features added
 --------------
 
@@ -17,6 +20,8 @@ Features added
   html_static_files
 * #8141: C: added a ``maxdepth`` option to :rst:dir:`c:alias` to insert
   nested declarations.
+* #8081: LaTeX: Allow to add LaTeX package via ``app.add_latex_package()`` until
+  just before writing .tex file
 
 Bugs fixed
 ----------
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 829bfc32b..d7ad21fff 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -26,6 +26,16 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``sphinx.builders.latex.LaTeXBuilder.usepackages``
+     - 3.3
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
+     - 3.3
+     - 5.0
+     - N/A
+
    * - ``sphinx.ext.autodoc.members_set_option()``
      - 3.2
      - 5.0
diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py
index ffb17d2eb..b58a44adf 100644
--- a/sphinx/builders/latex/__init__.py
+++ b/sphinx/builders/latex/__init__.py
@@ -24,7 +24,7 @@ from sphinx.builders.latex.constants import ADDITIONAL_SETTINGS, DEFAULT_SETTING
 from sphinx.builders.latex.theming import Theme, ThemeFactory
 from sphinx.builders.latex.util import ExtBabel
 from sphinx.config import Config, ENUM
-from sphinx.deprecation import RemovedInSphinx40Warning
+from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import NoUri, SphinxError
 from sphinx.locale import _, __
@@ -128,8 +128,6 @@ class LaTeXBuilder(Builder):
         self.docnames = []          # type: Iterable[str]
         self.document_data = []     # type: List[Tuple[str, str, str, str, str, bool]]
         self.themes = ThemeFactory(self.app)
-        self.usepackages = self.app.registry.latex_packages
-        self.usepackages_after_hyperref = self.app.registry.latex_packages_after_hyperref
         texescape.init()
 
         self.init_context()
@@ -179,10 +177,6 @@ class LaTeXBuilder(Builder):
             key = (self.config.latex_engine, self.config.language[:2])
             self.context.update(ADDITIONAL_SETTINGS.get(key, {}))
 
-        # Apply extension settings to context
-        self.context['packages'] = self.usepackages
-        self.context['packages_after_hyperref'] = self.usepackages_after_hyperref
-
         # Apply user settings to context
         self.context.update(self.config.latex_elements)
         self.context['release'] = self.config.release
@@ -203,6 +197,13 @@ class LaTeXBuilder(Builder):
             # Show the release label only if release value exists
             self.context.setdefault('releasename', _('Release'))
 
+    def update_context(self) -> None:
+        """Update template variables for .tex file just before writing."""
+        # Apply extension settings to context
+        registry = self.app.registry
+        self.context['packages'] = registry.latex_packages
+        self.context['packages_after_hyperref'] = registry.latex_packages_after_hyperref
+
     def init_babel(self) -> None:
         self.babel = ExtBabel(self.config.language, not self.context['babel'])
         if self.config.language and not self.babel.is_supported_language():
@@ -290,6 +291,7 @@ class LaTeXBuilder(Builder):
                 doctree['tocdepth'] = tocdepth
                 self.post_process_images(doctree)
                 self.update_doc_context(title, author, theme)
+                self.update_context()
 
             with progress_message(__("writing")):
                 docsettings._author = author
@@ -448,6 +450,18 @@ class LaTeXBuilder(Builder):
         filename = path.join(package_dir, 'templates', 'latex', 'sphinxmessages.sty_t')
         copy_asset_file(filename, self.outdir, context=context, renderer=LaTeXRenderer())
 
+    @property
+    def usepackages(self) -> List[Tuple[str, str]]:
+        warnings.warn('LaTeXBuilder.usepackages is deprecated.',
+                      RemovedInSphinx50Warning, stacklevel=2)
+        return self.app.registry.latex_packages
+
+    @property
+    def usepackages_after_hyperref(self) -> List[Tuple[str, str]]:
+        warnings.warn('LaTeXBuilder.usepackages_after_hyperref is deprecated.',
+                      RemovedInSphinx50Warning, stacklevel=2)
+        return self.app.registry.latex_packages_after_hyperref
+
 
 def patch_settings(settings: Any) -> Any:
     """Make settings object to show deprecation messages."""
diff --git a/sphinx/testing/util.py b/sphinx/testing/util.py
index 5ac334068..80ca84cb3 100644
--- a/sphinx/testing/util.py
+++ b/sphinx/testing/util.py
@@ -21,7 +21,6 @@ from docutils.nodes import Node
 from docutils.parsers.rst import directives, roles
 
 from sphinx import application, locale
-from sphinx.builders.latex import LaTeXBuilder
 from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.testing.path import path
@@ -141,7 +140,6 @@ class SphinxTestApp(application.Sphinx):
 
     def cleanup(self, doctrees: bool = False) -> None:
         ModuleAnalyzer.cache.clear()
-        LaTeXBuilder.usepackages = []
         locale.translators.clear()
         sys.path[:] = self._saved_path
         sys.modules.pop('autodoc_fodder', None)