LaTeX: enhanced boxes with padding, borders, shadows, rounded corners

- LaTeX: box padding (t,r,b,l), borders (t,r,b,l), shadows (x,y) or radii - LaTeX: fix #10650 via usage of our own sophisticated \fcolorbox - LaTeX: user interface via 'sphinxsetup' to enhanced code-blocks frames - LaTeX: user interface via 'sphinxsetup' to enhanced topic boxes - LaTeX: CSS-named-alikes 'sphinxsetup' options for code-blocks and topics - LaTeX: CSS-named-alikes 'sphinxsetup' keys for warning type notices (fix #10651) - LaTeX: documentation of the new CSS-like options
sphinx-doc · Jul 9, 2022 · 60419d9 · 60419d9
1 parent 1f21e97
commit 60419d9
Show file tree

Hide file tree

Showing 7 changed files with 1,450 additions and 339 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -77,7 +77,8 @@
     'sphinxsetup': """%
 VerbatimColor={RGB}{242,242,242},%
 VerbatimBorderColor={RGB}{32,32,32},%
-verbatimradius=3pt%
+pre_border-radius=3pt,%
+pre_box-decoration-break=slice,%
 """,
 }
 latex_show_urls = 'footnote'

diff --git a/doc/latex.rst b/doc/latex.rst
@@ -8,21 +8,21 @@ LaTeX customization
 
    \begingroup
    \sphinxsetup{%
-         verbatimborder=2pt,
-         verbatimsep=5pt,
-         verbatimradius=5pt,
-         VerbatimColor={named}{OldLace},
-         VerbatimBorderColor={named}{Gold},
+         pre_border-width=2pt,
+         pre_padding=5pt,
+         pre_border-radius=5pt,
+         pre_background-TeXcolor={named}{OldLace},
+         pre_border-TeXcolor={named}{Gold},
          TitleColor={named}{DarkGoldenrod},
          hintBorderColor={named}{LightCoral},
          attentionborder=3pt,
          attentionBorderColor={named}{Crimson},
          attentionBgColor={named}{FloralWhite},
          noteborder=2pt,
          noteBorderColor={named}{Olive},
-         cautionborder=3pt,
-         cautionBorderColor={named}{Cyan},
-         cautionBgColor={named}{LightCyan}}
+         div.caution_border-width=3pt,
+         div.caution_border-TeXcolor={named}{Cyan},
+         div.caution_background-TeXcolor={named}{LightCyan}}
    \relax
 
 Unlike :ref:`the HTML builders <html-themes>`, the ``latex`` builder does not
@@ -65,7 +65,10 @@ The ``latex_elements`` configuration setting
 
 A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
 into the generated ``.tex`` files.  Its ``'sphinxsetup'`` key is described
-:ref:`separately <latexsphinxsetup>`.
+:ref:`separately <latexsphinxsetup>`.  It allows also local configurations
+inserted in generated files, via :rst:dir:`raw` directives.  For example, in
+the PDF documentation this chapter is styled especially, as will be described
+later.
 
 Keys that you may want to override include:
 
@@ -575,35 +578,30 @@ The colors used in the above are provided by the ``svgnames`` option of the
    }
 
 It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
-directly into the body of the document, via the help of the :rst:dir:`raw`
+directly into the body of the document, via the help of the ``raw``
 directive. This chapter is styled in the PDF output using the following at the
 start of the chapter::
 
   .. raw:: latex
 
      \begingroup
      \sphinxsetup{%
-           % These were used as defaults for the whole sphinx.pdf
-           % VerbatimColor={RGB}{242,242,242},%
-           % VerbatimBorderColor={RGB}{32,32,32},%
-           % verbatimradius=3pt,%
-           % New definitions for this chapter code-blocks only:
-           VerbatimColor={named}{OldLace},
-           VerbatimBorderColor={named}{Gold},
-           verbatimradius=5pt,
-           verbatimsep=5pt,
-           verbatimborder=2pt,
-           % Other configuration for this chapter only:
-           TitleColor={named}{DarkGoldenrod},
-           hintBorderColor={named}{LightCoral},
-           attentionborder=3pt,
-           attentionBorderColor={named}{Crimson},
-           attentionBgColor={named}{FloralWhite},
-           noteborder=2pt,
-           noteBorderColor={named}{Olive},
-           cautionborder=3pt,
-           cautionBorderColor={named}{Cyan},
-           cautionBgColor={named}{LightCyan}}
+         pre_border-width=2pt,
+         pre_padding=5pt,
+         pre_border-radius=5pt,
+         pre_background-TeXcolor={named}{OldLace},
+         pre_border-TeXcolor={named}{Gold},
+         TitleColor={named}{DarkGoldenrod},
+         hintBorderColor={named}{LightCoral},
+         attentionborder=3pt,
+         attentionBorderColor={named}{Crimson},
+         attentionBgColor={named}{FloralWhite},
+         noteborder=2pt,
+         noteBorderColor={named}{Olive},
+         div.caution_border-width=3pt,
+         div.caution_border-TeXcolor={named}{Cyan},
+         div.caution_background-TeXcolor={named}{LightCyan}%
+     }
 
 And this is placed at the end of the chapter source to end the scope of
 the configuration::
@@ -852,32 +850,6 @@ Do not use quotes to enclose values, whether numerical or strings.
 
     Default: ``\fboxrule``
 
-``verbatimradius``
-    The radius of the rounded corners of the frame around :rst:dir:`code-block`\ s.
-
-    Default: ``0pt``
-
-    .. versionadded:: 5.1.0
-
-       If non-zero, it will trigger the loading of LaTeX package pict2e_.
-
-       .. caution::
-
-          The interface will remain experimental during the 5.x cycle: the
-          feature itself will remain, but the interface may evolve to include
-          other display elements such as admonitions.  For the latter it is
-          actually already possible for LaTeX-expert Sphinx users to use
-          functionalities of LaTeX packages such as tcolorbox_, via
-          redefinitions of the ``sphinxheavybox`` and ``sphinxlightbox``
-          `Environments`_.  This would be more difficult for code-blocks, and
-          this key achieves it.  The pict2e_ interface to some basic PDF
-          graphics operations is much more light-weight than the pgf_
-          framework used by tcolorbox_.
-
-    .. _pict2e: https://ctan.org/pkg/pict2e
-    .. _tcolorbox: https://ctan.org/pkg/tcolorbox
-    .. _pgf: https://ctan.org/pkg/pgf
-
 ``shadowsep``
     The separation between contents and frame for :dudir:`contents` and
     :dudir:`topic` boxes.
@@ -982,6 +954,212 @@ Do not use quotes to enclose values, whether numerical or strings.
                               ``errorborder``
 
 
+Additional  CSS-like ``'sphinxsetup'`` keys
+-------------------------------------------
+
+.. versionadded:: 5.1.0
+
+
+At ``5.1.0`` the LaTeX styling possibilities have been significantly enhanced.
+Code-blocks, topic directives, and the five warning-type directives each now possess:
+
+- four border-widths parameters,
+- four padding parameters,
+- four radius parameters (only circular arcs) for the corners,
+- optional shadow, with x-offset and y-offset being possibly negative,
+  and the shadow possibly inset,
+- colors for background, border and shadow.
+
+All those options have been named in a CSS-like way.  Indeed, in future it is
+envisioned to allow these settings to be specified either in an external file,
+or in a string variable which would be parsed to extract from CSS the
+selectors and properties which are understood.
+
+Currently though this is added via a bunch of new ``'sphinxsetup'`` keys
+whose names will be given now.
+
+.. important:: Low-level LaTeX errors causing a build failure can happen if
+   the input syntax is not respected.  In particular properties for colours,
+   whose names end with ``TeXcolor``, must be input as for the other colour
+   related options previously described, i.e. for example::
+
+     ...<other options>
+     div.warning_border-color={rgb}{1,0,0},%
+     ...<other options>
+
+   A colon will not be accepted in place of the equal sign which is
+   expected by the LaTeX syntax.
+   Do not insert spaces in the input.  With the exception of the
+   ``box-shadow`` all dimensional parameters expect a unique dimension
+   not a space separated list of dimensions.
+
+Options for code-blocks:
+
+- ``pre_border-top-width``,
+- ``pre_border-right-width``,
+- ``pre_border-bottom-width``,
+- ``pre_border-left-width``,
+- ``pre_border-width``, beware that this is a *single* dimension.  Its
+  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.
+- ``pre_padding-top``,
+- ``pre_padding-right``,
+- ``pre_padding-bottom``,
+- ``pre_padding-left``,
+- ``pre_padding``, again this is a single dimension.  Its default is the
+  setting of ``\fboxsep`` i.e. normally ``3pt``.
+- ``pre_border-top-left-radius``,
+- ``pre_border-top-right-radius``,
+- ``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``.
+- ``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
+  two dimensions followed by the word ``inset``.  The x-offset and y-offset
+  may be negative.  The defaults is ``none``.
+- ``pre_border-TeXcolor``,
+- ``pre_background-TeXcolor``,
+- and ``pre_box-shadow-TeXcolor`` 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.
+
+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 corners.
+
+.. note::
+
+   Rounded boxes are done using the pict2e_ interface to some basic PDF
+   graphics operations.  If this LaTeX package can not be found the build will
+   proceed and render all boxes with straight corners.
+
+.. _pict2e: https://ctan.org/pkg/pict2e
+
+
+Options for topic boxes:
+
+- ``aside.topic_border-top-width``,
+- ``aside.topic_border-right-width``,
+- ``aside.topic_border-bottom-width``,
+- ``aside.topic_border-left-width``,
+- ``aside.topic_border-width``, beware that this is a *single* dimension.  Its
+  default, and the ones of the separate widths is the setting of ``\fboxrule``
+  in the preamble, i.e. normally ``0.4pt``.
+- ``aside.topic_box-decoration-break`` is currently ignored.
+- ``aside.topic_padding-top``,
+- ``aside.topic_padding-right``,
+- ``aside.topic_padding-bottom``,
+- ``aside.topic_padding-left``,
+- ``aside.topic_padding``, again this is a single dimension.  Its default is `5pt`.
+- ``aside.topic_border-top-left-radius``,
+- ``aside.topic_border-top-right-radius``,
+- ``aside.topic_border-bottom-right-radius``,
+- ``aside.topic_border-bottom-left-radius``,
+- ``aside.topic_border-radius``, are all single dimensions which default to ``0pt``.
+- ``aside.topic_box-shadow`` defaults to ``4pt 4pt``.
+- ``aside.topic_border-TeXcolor``,
+- ``aside.topic_background-TeXcolor``,
+- ``aside.topic_box-shadow-TeXcolor`` 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.
+
+Options for warning directive:
+
+- ``div.warning_border-top-width``,
+- ``div.warning_border-right-width``,
+- ``div.warning_border-bottom-width``,
+- ``div.warning_border-left-width``,
+- ``div.warning_border-width``, beware that this is a *single* dimension.  Its
+  default, and the ones of the separate widths is ``1pt``.
+- ``div.warning_box-decoration-break`` is currently ignored.
+- ``div.warning_padding-top``,
+- ``div.warning_padding-right``,
+- ``div.warning_padding-bottom``,
+- ``div.warning_padding-left``,
+- ``div.warning_padding``, again this is a single dimension.  Its
+  default is computed by some formula which gives normally ``6.2pt``.  There
+  was no such parameter available formerly, and changing the border-width via
+  the ``warningborder`` option had an implicit impact on padding parameter to
+  keep their sum at a constant value ``7.2pt``.  Please configure padding now
+  directly if the border-width is changed if you want to keep former behaviour.
+- ``div.warning_border-top-left-radius``,
+- ``div.warning_border-top-right-radius``,
+- ``div.warning_border-bottom-right-radius``,
+- ``div.warning_border-bottom-left-radius``,
+- ``div.warning_border-radius``, are all single dimensions which default to ``0pt``.
+- ``div.warning_box-shadow`` defaults to ``none``.
+- ``div.warning_border-TeXcolor``,
+- ``div.warning_background-TeXcolor``,
+- ``div.warning_box-shadow-TeXcolor`` 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.
+
+Exactly the same options with same defaults are available with ``warning``
+replaced by one of ``caution``, ``attention``, ``danger``, ``error``.
+
+The following legacy behaviour of the PDF layout is currently not
+customizable:
+
+- for code-blocks, padding and border-width (and shadow if one adds one) will go
+  into the margin; the code lines remain at the same place independently of
+  the values of the padding and border-width, except for being shifted
+  vertically of course to not overwrite other text.
+
+- for topic boxes and warning-type-notices only the shadows will go into page
+  margin.
+
+There is no separate customizability of ``contents`` and ``topic`` directive.
+The ``note``-style admonition directives admit no such customization interface
+at this stage.
+
+Here is a random example which has been tested:
+
+.. code-block::
+
+   latex_elements = {
+       'sphinxsetup': """%
+       % VerbatimColor={RGB}{242,242,242},%  old option, still available
+       pre_background-TeXcolor={RGB}{242,242,242},%
+       pre_border-TeXcolor={RGB}{32,32,32},%
+       pre_box-decoration-break=slice,
+       pre_border-top-width=5pt,
+       pre_border-right-width=10pt,
+       pre_border-bottom-width=15pt,
+       pre_border-left-width=20pt,
+       pre_border-width=3pt,
+       pre_border-top-left-radius=20pt,
+       pre_border-top-right-radius=0pt,
+       pre_border-bottom-right-radius=20pt,
+       pre_border-bottom-left-radius=0pt,
+       pre_box-shadow=10pt 10pt,
+       pre_box-shadow-TeXcolor={RGB}{192,192,192},
+      %
+       aside.topic_border-TeXcolor={RGB}{102,102,102},%
+       aside.topic_box-shadow-TeXcolor={RGB}{187,187,187},%
+       aside.topic_background-TeXcolor={RGB}{238,238,255},%
+       aside.topic_border-bottom-right-radius=10pt,%
+       aside.topic_border-top-right-radius=10pt,%
+       aside.topic_border-width=2pt,%
+       aside.topic_box-shadow=10pt 10pt,%
+      %
+       div.danger_border-width=10pt,%
+       div.danger_background-TeXcolor={rgb}{0.6,.8,0.8},%
+       div.danger_border-TeXcolor={RGB}{64,64,64},%
+       div.danger_box-shadow=-7pt 7pt,%
+       div.danger_box-shadow-TeXcolor={RGB}{192,192,192},%
+       div.danger_border-bottom-left-radius=15pt,%
+      """,
+      }
+
+In future, it is hoped to add further CSS properties such as ``font`` or
+``color``.
+
+
 LaTeX macros and environments
 -----------------------------