LaTeX: switch to some nicer defaults for tables and code-blocks (#10924)

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
 ----------
 

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

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``,

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 <tablecolors>` 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`).

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])

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,13 +396,15 @@ 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
 }
 \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

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')