latex: Allow to add LaTeX package after hyperref loaded via API

sphinx/application.py

@@ -968,12 +968,14 @@ class Sphinx:
 
         self.add_css_file(filename, **attributes)
 
-    def add_latex_package(self, packagename: str, options: str = None) -> None:
+    def add_latex_package(self, packagename: str, options: str = None,
+                          after_hyperref: bool = False) -> None:
         r"""Register a package to include in the LaTeX source code.
 
         Add *packagename* to the list of packages that LaTeX source code will
         include.  If you provide *options*, it will be taken to `\usepackage`
-        declaration.
+        declaration.  If you set *after_hyperref* truthy, the package will be
+        loaded after ``hyperref`` package.
 
         .. code-block:: python
 
@@ -983,8 +985,11 @@ class Sphinx:
            # => \usepackage[foo,bar]{mypackage}
 
         .. versionadded:: 1.3
+        .. versionadded:: 3.1
+
+           *after_hyperref* option.
         """
-        self.registry.add_latex_package(packagename, options)
+        self.registry.add_latex_package(packagename, options, after_hyperref)
 
     def add_lexer(self, alias: str, lexer: Union[Lexer, "Type[Lexer]"]) -> None:
         """Register a new lexer for source code.

sphinx/builders/latex/__init__.py

@@ -129,6 +129,7 @@ class LaTeXBuilder(Builder):
         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()
@@ -180,6 +181,7 @@ class LaTeXBuilder(Builder):
 
         # 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)

sphinx/registry.py

@@ -98,6 +98,8 @@ class SphinxComponentRegistry:
         #: LaTeX packages; list of package names and its options
         self.latex_packages = []        # type: List[Tuple[str, str]]
 
+        self.latex_packages_after_hyperref = []     # type: List[Tuple[str, str]]
+
         #: post transforms; list of transforms
         self.post_transforms = []       # type: List[Type[Transform]]
 
@@ -363,9 +365,12 @@ class SphinxComponentRegistry:
         logger.debug('[app] adding js_file: %r, %r', filename, attributes)
         self.js_files.append((filename, attributes))
 
-    def add_latex_package(self, name: str, options: str) -> None:
+    def add_latex_package(self, name: str, options: str, after_hyperref: bool = False) -> None:
         logger.debug('[app] adding latex package: %r', name)
-        self.latex_packages.append((name, options))
+        if after_hyperref:
+            self.latex_packages_after_hyperref.append((name, options))
+        else:
+            self.latex_packages.append((name, options))
 
     def add_enumerable_node(self, node: "Type[Node]", figtype: str,
                             title_getter: TitleGetter = None, override: bool = False) -> None:

sphinx/templates/latex/latex.tex_t

@@ -46,6 +46,14 @@
 <%- endfor %>
 
 <%= hyperref %>
+<%- for name, option in packages_after_hyperref %>
+<%- if option %>
+\usepackage[<%= option %>]{<%= name %>}
+<%- else %>
+\usepackage{<%= name %>}
+<%- endif %>
+<%- endfor %>
+
 <%= contentsname %>
 \usepackage{sphinxmessages}
 <%= tocdepth %>