Repository: sphinx-doc/sphinx

Issue:
LaTeX: support for seealso directive should be via an environment to allow styling
The LaTeX writer support for the "seealso" directive produces this kind of mark-up:

```latex
Text before


\sphinxstrong{See also:}


This is contents of seealso directive



Text after
```

from

```rest
Text before

.. seealso::

   This is contents of seealso directive

Text after
```

This makes impossible styling on the LaTeX side the way the contents are rendered (for example use some background color).

This is in contrast to most other elements of the LaTeX writer output, hence is a bug.

Admittedly [our docs](https://www.sphinx-doc.org/en/1.5/markup/para.html#directive-seealso) says

> The content of the seealso directive should be a reST definition list. Example:

Still, a ``sphinxseealso`` environment would be useful to customize the included definition list. Besides there does not seem much rationale for restricting the contents of "seealso" directive to be definition lists only. Our doc says

>  For the HTML output, it is shown boxed off from the main flow of the text.

but without a LaTeX "sphinxseealso" environment, similar effect or even non similar is impossible for PDF output.



**Environment info**
- Sphinx version: 2.1.x and earlier

**Additional context**
- motivated from a [discussion of the Sphinx user group](https://groups.google.com/d/msgid/sphinx-users/qoelng%247t62%241%40blaine.gmane.org) 




Discussion:
jfbu: Linting via Ruff fails as is the case currently for master at 08ca934ff for unrelated reasons. I will merge now because this code is a priori not impacting PDF output, only LaTeX mark-up.

Patch:
diff --git a/CHANGES b/CHANGES
index 51f8d06b2..04e86c8d5 100644
--- 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
index 8e97ff2c1..5ce00016f 100644
--- 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
index 573a4d94b..bf7bba2c9 100644
--- 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
index d2a63daf2..aa506a343 100644
--- 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
index 7e78ea2ed..70dec716d 100644
--- 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')):


Test patch:
diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py
index a59e8525c..35947d372 100644
--- 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):