From c099e5be12350150eb0d16cc32334f66410b852f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 17 Oct 2022 00:12:56 +0200 Subject: [PATCH 1/5] LaTeX: switch to some nicer defaults for tables and code-blocks --- doc/conf.py | 7 ------- doc/latex.rst | 24 +++++++++++++----------- doc/usage/configuration.rst | 7 ++++--- sphinx/builders/latex/__init__.py | 2 +- sphinx/texinputs/sphinx.sty | 17 ++++++++++------- 5 files changed, 28 insertions(+), 29 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 5826fefa60f..45089831f84 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -77,16 +77,9 @@ {\footnotesize\raggedright\printindex} {\begin{sphinxtheindex}\end{sphinxtheindex}} ''', - 'sphinxsetup': """% -VerbatimColor=black!5,% tests 5.3.0 extended syntax -VerbatimBorderColor={RGB}{32,32,32},% -pre_border-radius=3pt,% -pre_box-decoration-break=slice,% -""", } latex_show_urls = 'footnote' latex_use_xindy = True -latex_table_style = ['booktabs', 'colorrows'] autodoc_member_order = 'groupwise' autosummary_generate = False diff --git a/doc/latex.rst b/doc/latex.rst index e8fcb95f84c..54bb1d927cb 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -863,12 +863,16 @@ Do not use quotes to enclose values, whether numerical or strings. ``VerbatimColor`` The background colour for :rst:dir:`code-block`\ s. - Default: ``{rgb}{1,1,1}`` (white) + Default: ``{gray}{0.95}`` + + .. versionchanged:: 6.0.0 ``VerbatimBorderColor`` The frame color. - Default: ``{rgb}{0,0,0}`` (black) + Default: ``{RGB}{32,32,32}`` + + .. versionchanged:: 6.0.0 ``VerbatimHighlightColor`` The color for highlighted lines. @@ -1070,7 +1074,7 @@ Options for code-blocks: default, and the ones of the separate widths is the setting of ``\fboxrule`` in the preamble, i.e. normally ``0.4pt``. - ``pre_box-decoration-break`` can be set to ``clone`` or ``slice``, default - is ``clone`` for backwards compatibility. + is ``slice`` since 6.0.0. (former default was ``clone``). - | ``pre_padding-top``, | ``pre_padding-right``, | ``pre_padding-bottom``, @@ -1082,7 +1086,7 @@ Options for code-blocks: | ``pre_border-bottom-right-radius``, | ``pre_border-bottom-left-radius``, | ``pre_border-radius``, are all single dimensions (rounded corners are - circular arcs only), which default to ``0pt``. + circular arcs only), which default (since 6.0.0) to ``3pt``. - ``pre_box-shadow`` is special in so far as it may be the ``none`` keyword, or a single dimension which will be assigned to both x-offset and y-offset, or two dimensions, or @@ -1092,9 +1096,9 @@ Options for code-blocks: | ``pre_background-TeXcolor``, | ``pre_box-shadow-TeXcolor``. - They must all be of the format as accepted by LaTeX ``\definecolor``. They - default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}`` and ``{rgb}{0,0,0}`` - respectively. + They + default to ``{RGB}{32,32,32}``, ``{gray}{0.95}`` and ``{rgb}{0,0,0}`` + respectively (since 6.0.0). If one of the radius parameters is positive, the separate border widths will be ignored and only the value set by ``pre_border-width`` will be used. Also, @@ -1138,8 +1142,7 @@ Options for topic boxes: | ``div.topic_background-TeXcolor``, | ``div.topic_box-shadow-TeXcolor``. - They must all be of the format as accepted by - LaTeX ``\definecolor``. They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}`` + They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}`` and ``{rgb}{0,0,0}`` respectively. Options for ``warning`` (and similarly for ``caution``, ``attention``, @@ -1180,8 +1183,7 @@ Options for ``warning`` (and similarly for ``caution``, ``attention``, | ``div.warning_background-TeXcolor``, | ``div.warning_box-shadow-TeXcolor``. - They must all be of the format as accepted by - LaTeX ``\definecolor``. They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}`` + They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}`` and ``{rgb}{0,0,0}`` respectively. In the above replace ``warning`` by one of ``caution``, ``attention``, diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 941b6038d9d..2642805fcd4 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2236,12 +2236,13 @@ These options influence LaTeX output. update your project to use instead the :ref:`latex table color configuration ` keys. - Default: ``[]`` + Default: ``['booktabs','colorrows']`` .. versionadded:: 5.3.0 - If using ``'booktabs'`` or ``'borderless'`` it seems recommended to also - opt for ``'colorrows'``... + .. versionchanged:: 6.0.0 + + Modify default from ``[]`` to ``['booktabs', 'colorrows']``. Each table can override the global style via ``:class:`` option, or ``.. rst-class::`` for no-directive tables (cf. :ref:`table-directives`). diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py index 2979589db98..3344095f8bd 100644 --- a/sphinx/builders/latex/__init__.py +++ b/sphinx/builders/latex/__init__.py @@ -527,7 +527,7 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.add_config_value('latex_show_pagerefs', False, False) app.add_config_value('latex_elements', {}, False) app.add_config_value('latex_additional_files', [], False) - app.add_config_value('latex_table_style', [], False, [list]) + app.add_config_value('latex_table_style', ['booktabs', 'colorrows'], False, [list]) app.add_config_value('latex_theme', 'manual', False, [str]) app.add_config_value('latex_theme_options', {}, False) app.add_config_value('latex_theme_path', [], False, [list]) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 0ac55cc495b..573a4d94bce 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -234,8 +234,8 @@ will be set to white}% \sphinxDeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}} \sphinxDeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}} \sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}} -\sphinxDeclareColorOption{VerbatimColor}{{rgb}{1,1,1}} -\sphinxDeclareColorOption{VerbatimBorderColor}{{rgb}{0,0,0}} +\sphinxDeclareColorOption{VerbatimColor}{{gray}{0.95}} +\sphinxDeclareColorOption{VerbatimBorderColor}{{RGB}{32,32,32}} % all other colours will be named with a "sphinx" prefix \newcommand*{\sphinxDeclareSphinxColorOption}[2]{% % set the initial default; only \definecolor syntax for defaults! @@ -321,7 +321,8 @@ will be set to white}% \let\spx@pre@border@left \spx@pre@border@top \expandafter\let\expandafter\KV@sphinx@verbatimborder \csname KV@sphinx@pre_border-width\endcsname -\newif\ifspx@pre@border@open % defaults to false (at least for 5.x series) +\newif\ifspx@pre@border@open +\spx@pre@border@opentrue % 6.0.0 (i.e. "slice") \define@key{sphinx}{pre_box-decoration-break}% {\begingroup\edef\spx@tempa{#1}\expandafter\endgroup \ifx\spx@tempa\spxstring@clone @@ -361,10 +362,10 @@ will be set to white}% } % MEMO: keep in mind in using these macros in code elsewhere that they can % thus be dimen registers or simply dimensional specs such as 3pt -\let\spx@pre@radius@topleft \z@ -\let\spx@pre@radius@topright \z@ -\let\spx@pre@radius@bottomright\z@ -\let\spx@pre@radius@bottomleft \z@ +\def\spx@pre@radius@topleft {3pt}% +\let\spx@pre@radius@topright \spx@pre@radius@topleft +\let\spx@pre@radius@bottomright\spx@pre@radius@topleft +\let\spx@pre@radius@bottomleft \spx@pre@radius@topleft \AtBeginDocument{\if1\ifdim\spx@pre@radius@topleft>\z@0\fi \ifdim\spx@pre@radius@topright>\z@0\fi \ifdim\spx@pre@radius@bottomright>\z@0\fi @@ -395,6 +396,7 @@ will be set to white}% \spx@pre@box@shadow@setter none {} {} \@nnil % \newif\ifspx@pre@withbordercolor +\spx@pre@withbordercolortrue % 6.0.0 \define@key{sphinx}{pre_border-TeXcolor}{% \spx@pre@withbordercolortrue \spx@defineorletcolor{VerbatimBorderColor}#1\relax @@ -402,6 +404,7 @@ will be set to white}% \expandafter\let\expandafter\KV@sphinx@VerbatimBorderColor \csname KV@sphinx@pre_border-TeXcolor\endcsname \newif\ifspx@pre@withbackgroundcolor +\spx@pre@withbackgroundcolortrue % 6.0.0 \define@key{sphinx}{pre_background-TeXcolor}{% \spx@pre@withbackgroundcolortrue \spx@defineorletcolor{VerbatimColor}#1\relax From cb69cd3de45cfae4cdff3b5146038621971e7285 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 17 Oct 2022 00:53:36 +0200 Subject: [PATCH 2/5] Update LaTeX table tests --- tests/test_build_latex.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index 004fc021b68..f8b06562b51 100644 --- a/tests/test_build_latex.py +++ b/tests/test_build_latex.py @@ -1168,7 +1168,8 @@ def test_maxlistdepth_at_ten(app, status, warning): compile_latex_document(app, 'python.tex') -@pytest.mark.sphinx('latex', testroot='latex-table') +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'latex_table_style': []}) @pytest.mark.test_params(shared_result='latex-table') def test_latex_table_tabulars(app, status, warning): app.builder.build_all() @@ -1238,7 +1239,8 @@ def get_expected(name): assert actual == expected -@pytest.mark.sphinx('latex', testroot='latex-table') +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'latex_table_style': []}) @pytest.mark.test_params(shared_result='latex-table') def test_latex_table_longtable(app, status, warning): app.builder.build_all() @@ -1298,7 +1300,8 @@ def get_expected(name): assert actual == expected -@pytest.mark.sphinx('latex', testroot='latex-table') +@pytest.mark.sphinx('latex', testroot='latex-table', + confoverrides={'latex_table_style': []}) @pytest.mark.test_params(shared_result='latex-table') def test_latex_table_complex_tables(app, status, warning): app.builder.build_all() @@ -1329,8 +1332,7 @@ def get_expected(name): assert actual == expected -@pytest.mark.sphinx('latex', testroot='latex-table', - confoverrides={'latex_table_style': ['booktabs', 'colorrows']}) +@pytest.mark.sphinx('latex', testroot='latex-table') def test_latex_table_with_booktabs_and_colorrows(app, status, warning): app.builder.build_all() result = (app.outdir / 'python.tex').read_text(encoding='utf8') From b8cc96f4c09a4a495f30664d31b09edbdfd278d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 17 Oct 2022 10:50:22 +0200 Subject: [PATCH 3/5] Add CHANGES entry for #10924 and update latex docs --- CHANGES | 5 +++++ doc/latex.rst | 11 +++++++++++ 2 files changed, 16 insertions(+) diff --git a/CHANGES b/CHANGES index e1b9ccebfd3..04d91126039 100644 --- a/CHANGES +++ b/CHANGES @@ -43,6 +43,11 @@ Deprecated Features added -------------- +* #10924: LaTeX: adopt better looking defaults for tables and code-blocks. + See :confval:`latex_table_style` and the ``pre_border-radius`` and + ``pre_background-TeXcolor`` :ref:`additionalcss` for the former defaults + and how to re-enact them if desired. + Bugs fixed ---------- diff --git a/doc/latex.rst b/doc/latex.rst index 54bb1d927cb..ff6053942cf 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -867,6 +867,8 @@ Do not use quotes to enclose values, whether numerical or strings. .. versionchanged:: 6.0.0 + Formerly, it was ``{rgb}{1,1,1}`` (white). + ``VerbatimBorderColor`` The frame color. @@ -874,6 +876,8 @@ Do not use quotes to enclose values, whether numerical or strings. .. versionchanged:: 6.0.0 + Formerly it was ``{rgb}{0,0,0}`` (black). + ``VerbatimHighlightColor`` The color for highlighted lines. @@ -1100,6 +1104,13 @@ Options for code-blocks: default to ``{RGB}{32,32,32}``, ``{gray}{0.95}`` and ``{rgb}{0,0,0}`` respectively (since 6.0.0). +.. versionchanged:: 6.0.0 + Formerly ``pre_border-radius`` (aka ``VerbatimBorder``) was ``0pt`` + (i.e. straight corners) and the colours ``pre_border-TeXcolor`` + and ``pre_background-TeXcolor`` (aka ``VerbatimBorderColor`` and + ``VerbatimColor``) where ``{rgb}{0,0,0}`` (black border) and + ``{rgb}{1,1,1}`` (white background) respectively. + If one of the radius parameters is positive, the separate border widths will be ignored and only the value set by ``pre_border-width`` will be used. Also, if a shadow is present and is inset, the box will be rendered with straight From c01095dee681e91461d0135a243fea656b5d8389 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 17 Oct 2022 10:57:03 +0200 Subject: [PATCH 4/5] Forgot to document pre_box-decoration-break change of default --- doc/latex.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/latex.rst b/doc/latex.rst index ff6053942cf..e7f631aafc7 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1110,6 +1110,8 @@ Options for code-blocks: and ``pre_background-TeXcolor`` (aka ``VerbatimBorderColor`` and ``VerbatimColor``) where ``{rgb}{0,0,0}`` (black border) and ``{rgb}{1,1,1}`` (white background) respectively. + Also ``pre_box-decoration-break`` was changed from ``clone`` into + ``slice`` for "open" framing at pagebreaks. If one of the radius parameters is positive, the separate border widths will be ignored and only the value set by ``pre_border-width`` will be used. Also, From a53f8fbe3212fad34f541da98d250541ebe0a466 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 17 Oct 2022 11:11:31 +0200 Subject: [PATCH 5/5] One more tidbit in latex_table_style doc --- doc/usage/configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 2642805fcd4..4ddd16a0e93 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2236,7 +2236,7 @@ These options influence LaTeX output. update your project to use instead the :ref:`latex table color configuration ` keys. - Default: ``['booktabs','colorrows']`` + Default: ``['booktabs', 'colorrows']`` .. versionadded:: 5.3.0