LaTeX: add \sphinxnotetitle et al. to sphinxlatexadmonitions.sty

.github/workflows/main.yml

@@ -58,6 +58,12 @@ jobs:
         PYTHONWARNINGS: ""
     - name: Install Docutils ${{ matrix.docutils }}
       run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*"
+      if: "!endsWith(matrix.python, '-dev')"
+    - name: Install Docutils ${{ matrix.docutils }} (ignore warnings)
+      run: python -m pip install --upgrade "docutils==${{ matrix.docutils }}.*"
+      if: "endsWith(matrix.python, '-dev')"
+      env:
+        PYTHONWARNINGS: ""
     - name: Test with pytest
       run: python -m pytest -vv --durations 25
 

CHANGES

@@ -22,10 +22,6 @@ Incompatible changes
 Deprecated
 ----------
 
-* LaTeX: some internals of the ``sphinxadmonition`` environment have been
-  marked for removal at 7.0.0 in the :file:`sphinxlatexadmonitions.sty`.
-  Custom re-definitions of ``sphinxlightbox`` or ``sphinxheavybox`` will have
-  to be updated if they depended upon them.
 * #11247: Deprecate the legacy ``intersphinx_mapping`` format
 
 Features added
@@ -39,6 +35,9 @@ Features added
 * LaTeX: a command ``\sphinxbox`` for styling text elements with a (possibly
   rounded) box, optional background color and shadow, has been added.
   See :ref:`sphinxbox`. (refs: #11224)
+* LaTeX: add ``\sphinxnotetitle``, ..., ``\sphinxwarningtitle``, ..., for
+  an extra layer of mark-up freeing up ``\sphinxstrong`` for other uses.
+  See :ref:`latex-macros`.
 * LaTeX: :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip` can
   now each be styled as the other admonitions, i.e. possibly with a background
   color, individual border widths and paddings, possibly rounded corners, and
@@ -62,6 +61,8 @@ Bugs fixed
   respective to contents (when using rounded corners)
 * #11235: LaTeX: added ``\color`` in topic (or admonition) contents may cause color
   leak to the shadow and border at a page break
+* #11264: LaTeX: missing space before colon after "Voir aussi" for :rst:dir:`seealso`
+  directive in French (refs: #6744)
 * #11147: Fix source file/line number info in object description content and in
   other uses of ``nested_parse_with_titles``.  Patch by Jeremy Maitin-Shepard.
 * #11192: Restore correct parallel search index building.

doc/latex.rst

@@ -1464,6 +1464,16 @@ Macros
      ``\sphinxsamedocref``;     ``\emph{#1}``
      ``\sphinxparam``;          ``\emph{#1}``
      ``\sphinxoptional``; ``[#1]`` with larger brackets, see source
+     ``\sphinxnotetitle``;      ``\sphinxstrong{#1}<space>``
+     ``\sphinxhinttitle``;      *idem*
+     ``\sphinximportanttitle``; *idem*
+     ``\sphinxtiptitle``;       *idem*
+     ``\sphinxwarningtitle``;   *idem*
+     ``\sphinxcautiontitle``;   *idem*
+     ``\sphinxattentiontitle``; *idem*
+     ``\sphinxdangertitle``;    *idem*
+     ``\sphinxerrortitle``;     *idem*
+     ``\sphinxseealsotitle``;   ``\sphinxstrong{#1}\par\nopagebreak``
 
   .. versionadded:: 1.4.5
      Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
@@ -1478,6 +1488,17 @@ Macros
   .. versionadded:: 6.2.0
      ``\sphinxparam``, ``\sphinxsamedocref``
 
+  .. versionadded:: 6.2.0
+     ``\sphinxnotetitle`` et al.  The ``#1`` is the localized name of the
+     directive, with a final colon.  Wrap it as ``\sphinxremovefinalcolon{#1}``
+     if this final colon is to be removed.  Example:
+
+     .. code-block:: latex
+
+        \renewcommand\sphinxwarningtitle[1]{%
+          \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par
+        }
+
 - More text styling:
 
   .. csv-table::
@@ -1689,12 +1710,14 @@ Environments
      ``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 behavior: the localized ``See
-  also``, followed with a colon, will be rendered using ``\sphinxstrong``.
-  Nothing particular is done for the contents.
+  It takes one argument which will be the localized string ``See also``
+  followed with a colon.
 
   .. versionadded:: 6.1.0
+  .. versionchanged:: 6.2.0
+
+     Colon made part of the mark-up rather than being inserted by the
+     environment for coherence with how admonitions are handled generally.
 
 - The contents_ directive (with ``:local:`` option) and the
   :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -23,31 +23,36 @@
 \RequirePackage{framed}% used by sphinxheavybox
 %
 % Dependencies (they do not need to be defined at time of loading):
+%
 % - of course the various colour and dimension options handled via sphinx.sty
+%
 % - \sphinxstrong (for sphinxlightbox and sphinxheavybox)
+%
 % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
+%
 % - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
+%
+% - \sphinxnotetitle, ..., \sphinxwarningtitle, etc... which are used by
+%   default in the corresponding sphinx<notice> environments to replace at 6.2.0
+%   formerly hard-coded \sphinxstrong{#1}<space>
+%   Their definitions are in sphinxlatexstyletext.sty.  Also \sphinxseealsotitle
+
 
 % Provides: (also in sphinxlatexliterals.sty)
 \providecommand*\sphinxvspacefixafterfrenchlists{%
    \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
 }
 
 % Some are quite plain
-\newenvironment{sphinxseealso}[1]{\sphinxstrong{#1:}\par\nopagebreak}{}
+\newenvironment{sphinxseealso}[1]{\sphinxseealsotitle{#1}}{}
 
 % This \dimen register is a legacy relic from Sphinx 1.5 which is used now
 % only for sphinxlightbox.  It is set in the sphinxadmonition environment.
 \newdimen\spx@notice@border
 
-% 6.2.0: add support for the <type>_TeXcolor options for text color.
-% 6.2.0: use directly sphinx<type>BorderColor, not spx@notice@bordercolor,
-%        as the latter will probably be removed altogether at 7.0.0
 \newenvironment{sphinxlightbox}{%
-  % done in sphinxadmonition but its place should be here
-  % \spx@notice@border \dimexpr\csname spx@\spx@noticetype @border\endcsname\relax
   \par
-  \noindent{\color{sphinx\spx@noticetype BorderColor}%
+  \noindent{\color{spx@notice@bordercolor}%
             \rule{\linewidth}{\spx@notice@border}}%
   \par\nobreak
   {\parskip\z@skip\noindent}%
@@ -57,7 +62,7 @@
   % (we can't cancel that any earlier \vskip introduced a potential pagebreak)
   \sphinxvspacefixafterfrenchlists
   \nobreak\vbox{\noindent\kern\@totalleftmargin
-      {\color{sphinx\spx@noticetype BorderColor}%
+      {\color{spx@notice@bordercolor}%
        \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
              {\linewidth}{\spx@notice@border}}\hss}\allowbreak
   }% end of sphinxlightbox environment definition
@@ -72,33 +77,36 @@
 % \newenvironment{sphinxhint}[1]
 %   {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
 %
-% It was possible for user to \renewenvironment this to use sphinxheavybox,
-% but this had stopped functioning at 5.1.0 which had greatly enhanced the
-% sphinxheavybox environment and the needed support macros existed only for
-% warning, caution, attention, danger, and error admonitions.  At 6.1.0 a
-% patch was added to allow the \renewenvironment method to work again for
-% note, hint, important, tip to use sphinxheavybox.
-%
-% Then at 6.2.0, note, hint, important, tip can now access full customization
-% of sphinxheavybox: CSS-named alike options (if used) trigger sphinxheavybox.
-% The \renewenvironment method still works but then only common border width,
-% non-configurable padding, straight corners and no shadow are all implied,
-% as long as the related CSS-named options are not used.
+% The more complex definition below will branch to sphinxheavybox if a certain
+% boolean associated to the notice type is true.  This boolean is set to true
+% whenever a CSS-named alike options for the notice type has been used in
+% sphinxsetup.  The old coding as above would still work, with the new options
+% being then simply ignored.  A user redefinition will probably either use
+% directly sphinxlightbox or sphinxheavybox or something else, with no need to
+% test the boolean.
+%
+% 6.2.0 also adds one layer of mark-up via \sphinxnotetitle etc..., because
+% the former \sphinxstrong{#1}<space> used a too generic \sphinxstrong.  But
+% perhaps the #1 should be passed over to sphinx{light,heavy}box as parameter.
+% Unfortunately replacing these environments with one-parameter environments
+% would be potentially a breaking change.  Anyway, sphinxpackageboxes.sty does not
+% provide a "titled" box; the caption of code-blocks is handled by extra
+% code in sphinxVerbatim.
 \newenvironment{sphinxnote}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavynote heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinxnotetitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 \newenvironment{sphinxhint}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavyhint heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinxhinttitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 \newenvironment{sphinximportant}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavyimportant heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinximportanttitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 \newenvironment{sphinxtip}[1]
   {\edef\spx@env{sphinx\ifspx@opt@heavytip heavy\else light\fi box}%
-   \expandafter\begin\expandafter{\spx@env}\sphinxstrong{#1} }
+   \expandafter\begin\expandafter{\spx@env}\sphinxtiptitle{#1}}
   {\expandafter\end\expandafter{\spx@env}}
 
 % warning/caution/attention/danger/error  get more distinction
@@ -193,31 +201,35 @@
 % - Since 6.2.0, also note/hint/important/tip notices can use these options
 % and then they go automatically via sphinxheavybox.  If only the legacy options
 % are used, they keep using sphinxlightbox.
+%
+% - Since 6.2.0, \sphinxwarningtitle etc... add one level of mark-up (they
+% expand to \sphinxstrong{#1}<space> which was former hard-coded mark-up).
+% Example:
+% \renewcommand{\sphinxwarningtitle}[1]{\textbf{#1}\par\smallskip
+%   {\color{sphinxwarningBorderColor}\hrule height1pt}\smallskip}
 \newenvironment{sphinxwarning}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxwarningtitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxcaution}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxcautiontitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxattention}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxattentiontitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxdanger}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxdangertitle{#1}}{\end{sphinxheavybox}}
 \newenvironment{sphinxerror}[1]
-  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
+  {\begin{sphinxheavybox}\sphinxerrortitle{#1}}{\end{sphinxheavybox}}
 
 % the main dispatch for all types of notices
 \newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
   % can't use #1 directly in definition of end part
   \def\spx@noticetype {#1}%
-      % At 6.2.0, these definitions of spx@notice@bordercolor and
-      % spx@notice@bgcolor serve nothing at all for sphinxheavybox.  And the
-      % sphinxlightbox uses sphinx<type>BorderColor directly.  Not removing
-      % though, in case some people have redefined sphinxlightbox (or even
-      % sphinxheavybox) and expect these things to exist.
-      %
-      % This is marked for removal at 7.0.0.
-      \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
-      \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
-      \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
+  % those next three are a remnant of legacy code; they are not used at
+  % all by sphinxheavybox, and their usage could be disposed of by sphinxlightbox
+  % but we keep for backward compatibility and also because it may be simpler
+  % for user redefinitions to employ for example "spx@notice@bgcolor" and not
+  % the more bulky "sphinx\spx@noticetype BgColor".
+  \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
+  \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
+  \spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
   % trigger the sphinx<type> environment, #2=heading is passed as argument
   \begin{sphinx#1}{#2}%
   % 6.2.0 support of div.<type>_TeX{color,extras} options

sphinx/texinputs/sphinxlatexstyletext.sty

@@ -1,11 +1,35 @@
 %% TEXT STYLING
 %
 % change this info string if making any custom modification
-\ProvidesFile{sphinxlatexstyletext.sty}[2022/07/02 text styling]
+\ProvidesFile{sphinxlatexstyletext.sty}[2023/03/26 text styling]
 
 % Basically everything here consists of macros which are part of the latex
 % markup produced by the Sphinx latex writer
 
+% But those arise rather from the default definitions of the respective
+% latex environments done in sphinxlatexadmonitions.sty
+\def\sphinxnotetitle#1{\sphinxstrong{#1} }
+\let\sphinxhinttitle     \sphinxnotetitle % #1 holds the localized notice name
+\let\sphinximportanttitle\sphinxnotetitle % followed by a colon
+\let\sphinxtiptitle      \sphinxnotetitle
+\let\sphinxwarningtitle  \sphinxnotetitle
+\let\sphinxcautiontitle  \sphinxnotetitle
+\let\sphinxattentiontitle\sphinxnotetitle
+\let\sphinxdangertitle   \sphinxnotetitle
+\let\sphinxerrortitle    \sphinxnotetitle
+\def\sphinxseealsotitle#1{\sphinxstrong{#1}\par\nopagebreak}
+%
+% A utility to remove a final colon
+% (one must be certain the semi-colon is there)
+\protected\def\sphinxremovefinalcolon #1{%
+   % complications due to : possibly "active"
+   \begingroup\ifnum\catcode`:=\active
+                    \lccode`~=`:\lowercase{\def\x##1~}{##1}%
+               \else\def\x##1:{##1}\fi
+   \expandafter\endgroup\x#1%
+}%
+% See doc/latex.rst for an example.
+
 % Some custom font markup commands.
 \protected\def\sphinxstrong#1{\textbf{#1}}
 \protected\def\sphinxcode#1{\texttt{#1}}

sphinx/writers/latex.py

@@ -820,7 +820,7 @@ def depart_desc_annotation(self, node: Element) -> None:
 
     def visit_seealso(self, node: Element) -> None:
         self.body.append(BLANKLINE)
-        self.body.append(r'\begin{sphinxseealso}{%s}' % admonitionlabels['seealso'] + CR)
+        self.body.append(r'\begin{sphinxseealso}{%s:}' % admonitionlabels['seealso'] + CR)
 
     def depart_seealso(self, node: Element) -> None:
         self.body.append(BLANKLINE)

tests/test_build_latex.py

@@ -144,7 +144,7 @@ def test_writer(app, status, warning):
 
     assert 'Footnotes' not in result
 
-    assert ('\\begin{sphinxseealso}{See also}\n\n'
+    assert ('\\begin{sphinxseealso}{See also:}\n\n'
             '\\sphinxAtStartPar\n'
             'something, something else, something more\n'
             '\\begin{description}\n'