diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index ec7730c1f78..6468beb08f8 100644 --- a/.github/workflows/main.yml +++ b/.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 diff --git a/CHANGES b/CHANGES index 22ff492cd7e..db25ab557ae 100644 --- a/CHANGES +++ b/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. diff --git a/doc/latex.rst b/doc/latex.rst index 9fb283973c7..38e24a7abc8 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1464,6 +1464,16 @@ Macros ``\sphinxsamedocref``; ``\emph{#1}`` ``\sphinxparam``; ``\emph{#1}`` ``\sphinxoptional``; ``[#1]`` with larger brackets, see source + ``\sphinxnotetitle``; ``\sphinxstrong{#1}`` + ``\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``. diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index fa2d3d83a7c..3ae19de9fef 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -23,10 +23,20 @@ \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 environments to replace at 6.2.0 +% formerly hard-coded \sphinxstrong{#1} +% Their definitions are in sphinxlatexstyletext.sty. Also \sphinxseealsotitle + % Provides: (also in sphinxlatexliterals.sty) \providecommand*\sphinxvspacefixafterfrenchlists{% @@ -34,20 +44,15 @@ } % 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 _TeXcolor options for text color. -% 6.2.0: use directly sphinxBorderColor, 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} 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} 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 sphinxBorderColor 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 environment, #2=heading is passed as argument \begin{sphinx#1}{#2}% % 6.2.0 support of div._TeX{color,extras} options diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index b6a320a4a6d..33a247b719f 100644 --- a/sphinx/texinputs/sphinxlatexstyletext.sty +++ b/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}} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 1039c941c34..e50b11b4f29 100644 --- a/sphinx/writers/latex.py +++ b/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) diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index d1533ed5a23..f895f56d3e3 100644 --- a/tests/test_build_latex.py +++ b/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'