From 4dbb62b9cde353aa7d39d27938d8f7a7969cdd43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Sun, 3 Jul 2022 22:32:28 +0200 Subject: [PATCH 1/3] LaTeX: optional rounded corners for framing of code-blocks Via a new configuration verbatimradius of 'sphinxsetup', which defaults to 0pt. If this dimension is non zero, the LaTeX package pict2e will be loaded to help construct frames with rounded corners for code-blocks. And if the LaTeX package pict2e was not found, a LaTeX warning is issued during PDF build. --- doc/conf.py | 5 ++ doc/latex.rst | 45 +++++++++- sphinx/texinputs/sphinx.sty | 10 +++ sphinx/texinputs/sphinxpackageboxes.sty | 113 ++++++++++++++++++++++++ 4 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 sphinx/texinputs/sphinxpackageboxes.sty diff --git a/doc/conf.py b/doc/conf.py index a0d2f4df994..2f504f699f7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -74,6 +74,11 @@ {\footnotesize\raggedright\printindex} {\begin{sphinxtheindex}\end{sphinxtheindex}} ''', + 'sphinxsetup': """% +VerbatimColor={RGB}{242,242,242},% +VerbatimBorderColor={RGB}{32,32,32},% +verbatimradius=3pt% +""", } latex_show_urls = 'footnote' latex_use_xindy = True diff --git a/doc/latex.rst b/doc/latex.rst index 0140d0b2c9e..4d16445040e 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -8,8 +8,11 @@ LaTeX customization \begingroup \sphinxsetup{% - verbatimwithframe=false, + verbatimborder=2pt, + verbatimsep=5pt, + verbatimradius=5pt, VerbatimColor={named}{OldLace}, + VerbatimBorderColor={named}{Gold}, TitleColor={named}{DarkGoldenrod}, hintBorderColor={named}{LightCoral}, attentionborder=3pt, @@ -580,8 +583,17 @@ start of the chapter:: \begingroup \sphinxsetup{% - verbatimwithframe=false, + % 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, @@ -593,7 +605,8 @@ start of the chapter:: cautionBorderColor={named}{Cyan}, cautionBgColor={named}{LightCyan}} -The below is included at the end of the chapter:: +And this is placed at the end of the chapter source to end the scope of +the configuration:: .. raw:: latex @@ -839,6 +852,32 @@ 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. diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index b67722c1bfa..9b0b54c5624 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -74,6 +74,7 @@ % dimensions, we declare the \dimen registers here. \newdimen\sphinxverbatimsep \newdimen\sphinxverbatimborder +\newdimen\sphinxverbatimradius \newdimen\sphinxshadowsep \newdimen\sphinxshadowsize \newdimen\sphinxshadowrule @@ -87,6 +88,12 @@ \define@key{sphinx}{verbatimsep}{\sphinxverbatimsep\dimexpr #1\relax} \sphinxverbatimborder=\fboxrule \define@key{sphinx}{verbatimborder}{\sphinxverbatimborder\dimexpr #1\relax} +\sphinxverbatimradius=0pt + \define@key{sphinx}{verbatimradius}{% + \sphinxverbatimradius\dimexpr #1\relax + \ifdim\sphinxverbatimradius=\z@\else\RequirePackage{sphinxpackageboxes}\fi + } +\AtBeginDocument{\define@key{sphinx}{verbatimradius}{\sphinxverbatimradius\dimexpr #1\relax}} % topic boxes \sphinxshadowsep =5pt \define@key{sphinx}{shadowsep}{\sphinxshadowsep\dimexpr #1\relax} @@ -274,6 +281,9 @@ \input{sphinxlatexadmonitions.sty} \input{sphinxlatexliterals.sty} \input{sphinxlatexshadowbox.sty} +\ifdim\sphinxverbatimradius=\z@\else + \RequirePackage{sphinxpackageboxes} +\fi %% CONTAINERS diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty new file mode 100644 index 00000000000..b1d2620cacb --- /dev/null +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -0,0 +1,113 @@ +%% COLORED BOXES +% +% change this info string if making any custom modification +\ProvidesPackage{sphinxpackageboxes}[2022/07/04 v5.1.0 advanced colored boxes] + +% Currently, this file only provides a replacement to the \spx@verb@fcolorbox +% of sphinxlatexliterals.sty which will draw boxes with a frame having +% rounded corners, and a background color. +% +% It needs \sphinxverbatimsep, \sphinxverbatimborder and a new parameter +% \sphinxverbatimradius +% +% Executes \RequirePackage for: +% +% - pict2e. Ideally we would need a recent version of this package which +% allows dimensional arguments to its \moveto, \lineto, etc... +% but we add ourselves some wrapper to facilitate the usage. + + +% MEMO: we have also successfully tested usage of tcolorbox's \tcbox but +% decided to use pict2e.sty for the following reasons: +% 1- an order of magnitude faster for what we want to do, +% 2- orders of magnitude smaller dependency (tcolorbox uses the pgf TeX +% framework) +% 3- possibility to accomplish already quite fancy boxes with pict2e +% (and the additional coding as contributed here). + +% In this first installment, the caption and continuation hints of code-blocks +% are done exactly as formerly; only difference is in the rounded corrners. +% The space occupied is same, if nothing else is changed. + +\IfFileExists{pict2e.sty} + {\RequirePackage{pict2e}} + {\PackageWarningNoLine{sphinx}{% + The package pict2e is required for rounded boxes.\MessageBreak + It does not seem to be available on your system.\MessageBreak + The verbatimradius setting will thus be ignored}% + \AtEndDocument{\PackageWarningNoLine{sphinx}{% + I issued a warning which may have gotten lost in the\MessageBreak + gigantic console output: pict2e.sty was not found,\MessageBreak + and verbatimradius has been ignored}}\endinput} + +% First we define some wrapper to be able to use arguments being (only) +% dimensions or dimensional expressions. The \unitlength will always be 1pt. +\def\spx@moveto(#1,#2)% + {\expanded{\noexpand\moveto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)}} +\def\spx@lineto(#1,#2)% + {\expanded{\noexpand\lineto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)}} +% attention we use here [2] always; and there are two more mandatory +% arguments, angles, we don't need to worry about them here. +\def\spx@circlearc#1#2#3{\expanded{\noexpand\circlearc[2]% + {\strip@pt\dimexpr#1}{\strip@pt\dimexpr#2}{\strip@pt\dimexpr#3}}% +} + +% TODO: add top right bottom left padding possibilities. +\long\def\spx@verb@fcolorbox #1#2#3{% + % Prepare a box with the contents and reserved space for framing. + \setbox\tw@\hbox{\kern\dimexpr\sphinxverbatimborder+\sphinxverbatimsep\relax + {#3}\kern\dimexpr\sphinxverbatimborder+\sphinxverbatimsep\relax}% + \ht\tw@ \dimexpr\ht\tw@+\sphinxverbatimsep+\sphinxverbatimborder\relax + \dp\tw@ \dimexpr\dp\tw@+\sphinxverbatimsep+\sphinxverbatimborder\relax + \vbox{% +% Prepare a macro for path to be inserted in a picture environment for stroke +% and fill; the path will be redefined for each of fill or stroke. This macro +% does nothing yet. +\def\spx@dopath{% + \spx@moveto(\sphinxverbatimradius,\z@)% \z@ not 0 as our \spx@moveto is quite dumb + \spx@lineto(\wd\tw@-\sphinxverbatimborder-\sphinxverbatimradius,\z@)% + \spx@circlearc{\wd\tw@-\sphinxverbatimborder-\sphinxverbatimradius}% + {\sphinxverbatimradius}% + {\sphinxverbatimradius}{-90}{0}% + \spx@lineto(\wd\tw@-\sphinxverbatimborder,\ht\tw@+\dp\tw@-\sphinxverbatimborder-\sphinxverbatimradius)% + \spx@circlearc{\wd\tw@-\sphinxverbatimborder-\sphinxverbatimradius} + {\ht\tw@+\dp\tw@-\sphinxverbatimborder-\sphinxverbatimradius}% + {\sphinxverbatimradius}{0}{90}% + \spx@lineto(\sphinxverbatimradius,\ht\tw@+\dp\tw@-\sphinxverbatimborder)% + \spx@circlearc{\sphinxverbatimradius}% + {\ht\tw@+\dp\tw@-\sphinxverbatimborder-\sphinxverbatimradius}% + {\sphinxverbatimradius}{90}{180}% + \spx@lineto(\z@,\sphinxverbatimradius)% + \spx@circlearc{\sphinxverbatimradius}{\sphinxverbatimradius}{\sphinxverbatimradius}{180}{270}% +}% end of definition of \spx@dopath +% + #1% continuation hint attached above frame + % there will be a small "\lineskip" space here from TeX + % draw frame border _latest_ to avoid pdf viewer issue + % be careful not to cause "color push + contents + color pop" +% MEMO: when pict2e doth a path stroke, the path is in the middle of the line +% width, i.e. the line extends by half its width to the exterior of the filled +% path. This explains some 0.5 things below. + \hbox{\setlength{\unitlength}{1pt}% attention to space token here + \begin{picture}(\wd\tw@,\ht\tw@+\dp\tw@)% + (-.5\sphinxverbatimborder,-.5\sphinxverbatimborder)% + \color{VerbatimColor}% color for background + \spx@dopath\fillpath + \color{VerbatimBorderColor}% color for border +\ifspx@opt@verbatimwithframe % even with \sphinxverbatimborder set to 0pt, the + % stroke will produce a visible contour, so we + % must explicitly exclude doing it. + \linethickness{\sphinxverbatimborder}% + \spx@dopath\strokepath +\fi + \end{picture}}% + % now the contents + \kern-\dimexpr\ht\tw@+\dp\tw@\relax + \copy\tw@ % attention that #2 will need \wd\tw@ + \nointerlineskip + % TODO: add some \lineskip glue here, this is all in a \vbox so can't split + #2% continuation hint attached below frame + }% end of \vbox +}% + +\endinput From afaf57d9db5192dd4559cef4ca3f22dd914bc3b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 5 Jul 2022 10:09:59 +0200 Subject: [PATCH 2/3] LaTeX: fix previous commit for "old" LaTeX compatibility --- sphinx/texinputs/sphinxpackageboxes.sty | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index b1d2620cacb..880cee221be 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -89,8 +89,12 @@ % width, i.e. the line extends by half its width to the exterior of the filled % path. This explains some 0.5 things below. \hbox{\setlength{\unitlength}{1pt}% attention to space token here - \begin{picture}(\wd\tw@,\ht\tw@+\dp\tw@)% - (-.5\sphinxverbatimborder,-.5\sphinxverbatimborder)% +% work around for "old" LaTeX (2019 or earlier more or less, or we could use +% the "picture" package) +\expanded{\noexpand\begin{picture}% + (\strip@pt\wd\tw@,\strip@pt\dimexpr\ht\tw@+\dp\tw@)% + (\strip@pt\dimexpr-.5\sphinxverbatimborder,\strip@pt\dimexpr-.5\sphinxverbatimborder)% +}% \color{VerbatimColor}% color for background \spx@dopath\fillpath \color{VerbatimBorderColor}% color for border From 34fe9d0f842500afeba60bbaf0243a6e34ffe2dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 5 Jul 2022 16:51:22 +0200 Subject: [PATCH 3/3] LaTeX: fix (better) compatibility with "old" LaTeX There was no need for pre-expansion via \expanded and the latter was not available prior to TL2019 --- sphinx/texinputs/sphinxpackageboxes.sty | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index 880cee221be..f07b9b64c8a 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -43,13 +43,13 @@ % First we define some wrapper to be able to use arguments being (only) % dimensions or dimensional expressions. The \unitlength will always be 1pt. \def\spx@moveto(#1,#2)% - {\expanded{\noexpand\moveto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)}} + {\moveto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)} \def\spx@lineto(#1,#2)% - {\expanded{\noexpand\lineto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)}} + {\lineto(\strip@pt\dimexpr#1,\strip@pt\dimexpr#2)} % attention we use here [2] always; and there are two more mandatory % arguments, angles, we don't need to worry about them here. -\def\spx@circlearc#1#2#3{\expanded{\noexpand\circlearc[2]% - {\strip@pt\dimexpr#1}{\strip@pt\dimexpr#2}{\strip@pt\dimexpr#3}}% +\def\spx@circlearc#1#2#3{\circlearc[2]% + {\strip@pt\dimexpr#1}{\strip@pt\dimexpr#2}{\strip@pt\dimexpr#3}% } % TODO: add top right bottom left padding possibilities. @@ -89,12 +89,11 @@ % width, i.e. the line extends by half its width to the exterior of the filled % path. This explains some 0.5 things below. \hbox{\setlength{\unitlength}{1pt}% attention to space token here -% work around for "old" LaTeX (2019 or earlier more or less, or we could use -% the "picture" package) -\expanded{\noexpand\begin{picture}% +% work around for "old" LaTeX (we could use the "picture" package, this +% would add another dependency) + \begin{picture}% (\strip@pt\wd\tw@,\strip@pt\dimexpr\ht\tw@+\dp\tw@)% (\strip@pt\dimexpr-.5\sphinxverbatimborder,\strip@pt\dimexpr-.5\sphinxverbatimborder)% -}% \color{VerbatimColor}% color for background \spx@dopath\fillpath \color{VerbatimBorderColor}% color for border