Fix sphinx-doc#6744: support for seealso directive should be via an e…

…nvironment
jfbu · Jan 3, 2023 · 5fa97fe · 5fa97fe
1 parent 08ca934
commit 5fa97fe
Show file tree

Hide file tree

Showing 6 changed files with 31 additions and 4 deletions.
diff --git a/CHANGES b/CHANGES
@@ -16,6 +16,9 @@ Features added
 Bugs fixed
 ----------
 
+* #6744: LaTeX: support for seealso directive should be via an environment
+  to allow styling.
+
 Testing
 --------
 

diff --git a/doc/latex.rst b/doc/latex.rst
@@ -1431,6 +1431,14 @@ Environments
      parameters, such as ``noteBorderColor``, ``noteborder``,
      ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ...
 
+- Environment for the :rst:dir:`seealso` directive: ``sphinxseealso``.
+  It takes one argument which will be the localized string ``See also``.  Its
+  default definition maintains the legacy behaviour: the localized ``See
+  also``, followed with a colon, will be rendered using ``\sphinxstrong``.
+  Nothing particular is done for the contents.
+
+  .. versionadded:: 6.1.0
+
 - The :dudir:`contents` directive (with ``:local:`` option) and the
   :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
 

diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
@@ -6,7 +6,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2022/08/15 v5.3.0 LaTeX package (Sphinx markup)]
+\ProvidesPackage{sphinx}[2023/01/03 v6.1.0 LaTeX package (Sphinx markup)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but

diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty
@@ -1,10 +1,12 @@
 %% NOTICES AND ADMONITIONS
 %
 % change this info string if making any custom modification
-\ProvidesFile{sphinxlatexadmonitions.sty}[2022/07/03 admonitions]
+\ProvidesFile{sphinxlatexadmonitions.sty}[2023/01/03 admonitions]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
+% - sphinxseealso environment added at 6.1.0
+%
 % - sphinxadmonition (environment)
 %   This is a dispatch supporting
 %
@@ -31,6 +33,8 @@
 }
 
 % Some are quite plain
+\newenvironment{sphinxseealso}[1]{\sphinxstrong{#1:}\par\nopagebreak}{}
+
 % the spx@notice@bordercolor etc are set in the sphinxadmonition environment
 \newenvironment{sphinxlightbox}{%
   \par

diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py
@@ -821,11 +821,12 @@ def depart_desc_annotation(self, node: Element) -> None:
 
     def visit_seealso(self, node: Element) -> None:
         self.body.append(BLANKLINE)
-        self.body.append(r'\sphinxstrong{%s:}' % admonitionlabels['seealso'] + CR)
-        self.body.append(r'\nopagebreak' + BLANKLINE)
+        self.body.append(r'\begin{sphinxseealso}{%s}' % admonitionlabels['seealso'] + CR)
 
     def depart_seealso(self, node: Element) -> None:
         self.body.append(BLANKLINE)
+        self.body.append(r'\end{sphinxseealso}')
+        self.body.append(BLANKLINE)
 
     def visit_rubric(self, node: Element) -> None:
         if len(node) == 1 and node.astext() in ('Footnotes', _('Footnotes')):

diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py
@@ -135,6 +135,17 @@ def test_writer(app, status, warning):
 
     assert 'Footnotes' not in result
 
+    assert ('\\begin{sphinxseealso}{See also}\n\n'
+            '\\sphinxAtStartPar\n'
+            'something, something else, something more\n'
+            '\\begin{description}\n'
+            '\\sphinxlineitem{\\sphinxhref{http://www.google.com}{Google}}\n'
+            '\\sphinxAtStartPar\n'
+            'For everything.\n'
+            '\n'
+            '\\end{description}\n'
+            '\n\n\\end{sphinxseealso}\n\n' in result)
+
 
 @pytest.mark.sphinx('latex', testroot='warnings', freshenv=True)
 def test_latex_warnings(app, status, warning):