diff --git a/CHANGES b/CHANGES index e1b9ccebfd..04d9112603 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/conf.py b/doc/conf.py index 5826fefa60..45089831f8 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 e8fcb95f84..e7f631aafc 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -863,12 +863,20 @@ 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 + + Formerly, it was ``{rgb}{1,1,1}`` (white). ``VerbatimBorderColor`` The frame color. - Default: ``{rgb}{0,0,0}`` (black) + Default: ``{RGB}{32,32,32}`` + + .. versionchanged:: 6.0.0 + + Formerly it was ``{rgb}{0,0,0}`` (black). ``VerbatimHighlightColor`` The color for highlighted lines. @@ -1070,7 +1078,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 +1090,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 +1100,18 @@ 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). + +.. 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. + 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, @@ -1138,8 +1155,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 +1196,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 941b6038d9..4ddd16a0e9 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 2979589db9..3344095f8b 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 0ac55cc495..573a4d94bc 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 diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index 004fc021b6..f8b06562b5 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')