Skip to content

Commit

Permalink
Refactor LaTeX style files
Browse files Browse the repository at this point in the history 
This is a (continuation and) re-work of sphinx-doc#8769 (e6bf914)

I have reintegrated option handling and most package loading into the
original file sphinx.sty and reorganized completely the filenames of
secondary style files.

sphinx.sty had become too big and first sphinx-doc#8769 now this more definitive
refactoring is necessary to clarify structure, dependencies, and ease up
future maintenance.

Unfortunately this means a lot of moving around hunks of latex code with
some alterations.  I tried to carefully check everything is defined in
right order (as LaTeX being a macro expansion language, often one can
manipulate things before them being defined, nevertheless I checked
things are done in order).

Only simple thing is to review is that I added missing EOLs at last
lines of the extracted files...
  • Loading branch information
@jfbu
jfbu committed Jan 30, 2021
1 parent 1ebc9c2 commit 0c0be64
Show file tree
Hide file tree
Showing 17 changed files with 594 additions and 568 deletions.
298 changes: 243 additions & 55 deletions sphinx/texinputs/sphinx.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,105 +31,293 @@
}}


%% PACKAGES
%% OPTION HANDLING
%
% we delay handling of options to after having loaded packages, because
% of the need to use \definecolor.
\input{sphinxlatexrequirepackages.sty}

% We first handle options then load packages, but we need \definecolor from
% xcolor/color.

%% PYGMENTS
% stylesheet for highlighting with pygments
\RequirePackage{sphinxhighlight}
% fix baseline increase from Pygments latex formatter in case of error tokens
% and keep \fboxsep's scope local via added braces
\def\PYG@tok@err{%
\def\PYG@bc##1{{\setlength{\fboxsep}{-\fboxrule}%
\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}%
% FIXME: we should \RequirePackage{xcolor} always now
% The xcolor package draws better fcolorboxes around verbatim code
\IfFileExists{xcolor.sty}{
\RequirePackage{xcolor}
}{
\RequirePackage{color}
}
\def\PYG@tok@cs{%
\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}%
\def\PYG@bc##1{{\setlength{\fboxsep}{0pt}%
\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}%
}%


%% OPTION HANDLING
% Handle options via "kvoptions" (later loaded by hyperref anyhow)
\RequirePackage{kvoptions}
\SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix

% Sphinx legacy text layout: 1in margins on all four sides
\ifx\@jsc@uplatextrue\@undefined
\DeclareStringOption[1in]{hmargin}
\DeclareStringOption[1in]{vmargin}
\DeclareStringOption[.5in]{marginpar}
\else
% Japanese standard document classes handle \mag in a special way
\DeclareStringOption[\inv@mag in]{hmargin}
\DeclareStringOption[\inv@mag in]{vmargin}
\DeclareStringOption[.5\dimexpr\inv@mag in\relax]{marginpar}
\fi

\DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0}
\DeclareStringOption[-1]{numfigreset}
\DeclareBoolOption[false]{nonumfigreset}
\DeclareBoolOption[false]{mathnumfig}
% \DeclareBoolOption[false]{usespart}% not used
% dimensions, we declare the \dimen registers here.
\newdimen\sphinxverbatimsep
\newdimen\sphinxverbatimborder
\newdimen\sphinxshadowsep
\newdimen\sphinxshadowsize
\newdimen\sphinxshadowrule
% \DeclareStringOption is not convenient for the handling of these dimensions
% because we want to assign the values to the corresponding registers. Even if
% we added the code to the key handler it would be too late for the initial
% set-up and we would need to do initial assignments explicitely. We end up
% using \define@key directly.
% verbatim
\sphinxverbatimsep=\fboxsep
\define@key{sphinx}{verbatimsep}{\sphinxverbatimsep\dimexpr #1\relax}
\sphinxverbatimborder=\fboxrule
\define@key{sphinx}{verbatimborder}{\sphinxverbatimborder\dimexpr #1\relax}
% topic boxes
\sphinxshadowsep =5pt
\define@key{sphinx}{shadowsep}{\sphinxshadowsep\dimexpr #1\relax}
\sphinxshadowsize=4pt
\define@key{sphinx}{shadowsize}{\sphinxshadowsize\dimexpr #1\relax}
\sphinxshadowrule=\fboxrule
\define@key{sphinx}{shadowrule}{\sphinxshadowrule\dimexpr #1\relax}
% verbatim
\DeclareBoolOption[true]{verbatimwithframe}
\DeclareBoolOption[true]{verbatimwrapslines}
\DeclareBoolOption[true]{verbatimhintsturnover}
\DeclareBoolOption[true]{inlineliteralwraps}
\DeclareStringOption[t]{literalblockcappos}
\DeclareStringOption[r]{verbatimcontinuedalign}
\DeclareStringOption[r]{verbatimcontinuesalign}
% parsed literal
\DeclareBoolOption[true]{parsedliteralwraps}
% \textvisiblespace for compatibility with fontspec+XeTeX/LuaTeX
\DeclareStringOption[\textcolor{red}{\textvisiblespace}]{verbatimvisiblespace}
\DeclareStringOption % must use braces to hide the brackets
[{\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\m@th\hookrightarrow$}}}]%
{verbatimcontinued}
% notices/admonitions
% the dimensions for notices/admonitions are kept as macros and assigned to
% \spx@notice@border at time of use, hence \DeclareStringOption is ok for this
\newdimen\spx@notice@border
\DeclareStringOption[0.5pt]{noteborder}
\DeclareStringOption[0.5pt]{hintborder}
\DeclareStringOption[0.5pt]{importantborder}
\DeclareStringOption[0.5pt]{tipborder}
\DeclareStringOption[1pt]{warningborder}
\DeclareStringOption[1pt]{cautionborder}
\DeclareStringOption[1pt]{attentionborder}
\DeclareStringOption[1pt]{dangerborder}
\DeclareStringOption[1pt]{errorborder}
% footnotes
\DeclareStringOption[\mbox{ }]{AtStartFootnote}
% we need a public macro name for direct use in latex file
\newcommand*{\sphinxAtStartFootnote}{\spx@opt@AtStartFootnote}
% no such need for this one, as it is used inside other macros
\DeclareStringOption[\leavevmode\unskip]{BeforeFootnote}
% some font styling.
\DeclareStringOption[\sffamily\bfseries]{HeaderFamily}
% colours
% same problems as for dimensions: we want the key handler to use \definecolor.
% first, some colours with no prefix, for backwards compatibility
\newcommand*{\sphinxDeclareColorOption}[2]{%
\definecolor{#1}#2%
\define@key{sphinx}{#1}{\definecolor{#1}##1}%
}%
\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}}
% now the colours defined with "sphinx" prefix in their names
\newcommand*{\sphinxDeclareSphinxColorOption}[2]{%
% set the initial default
\definecolor{sphinx#1}#2%
% set the key handler. The "value" ##1 must be acceptable by \definecolor.
\define@key{sphinx}{#1}{\definecolor{sphinx#1}##1}%
}%
% Default color chosen to be as in minted.sty LaTeX package!
\sphinxDeclareSphinxColorOption{VerbatimHighlightColor}{{rgb}{0.878,1,1}}
% admonition boxes, "light" style
\sphinxDeclareSphinxColorOption{noteBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{hintBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{importantBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{tipBorderColor}{{rgb}{0,0,0}}
% admonition boxes, "heavy" style
\sphinxDeclareSphinxColorOption{warningBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{cautionBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{attentionBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{dangerBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{errorBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{warningBgColor}{{rgb}{1,1,1}}
\sphinxDeclareSphinxColorOption{cautionBgColor}{{rgb}{1,1,1}}
\sphinxDeclareSphinxColorOption{attentionBgColor}{{rgb}{1,1,1}}
\sphinxDeclareSphinxColorOption{dangerBgColor}{{rgb}{1,1,1}}
\sphinxDeclareSphinxColorOption{errorBgColor}{{rgb}{1,1,1}}

\DeclareDefaultOption{\@unknownoptionerror}
\ProcessKeyvalOptions*
% don't allow use of maxlistdepth via \sphinxsetup.
\DisableKeyvalOption{sphinx}{maxlistdepth}
\DisableKeyvalOption{sphinx}{numfigreset}
\DisableKeyvalOption{sphinx}{nonumfigreset}
\DisableKeyvalOption{sphinx}{mathnumfig}
% FIXME: this is unrelated to an option, move this elsewhere
% To allow hyphenation of first word in narrow contexts; no option,
% customization to be done via 'preamble' key
\newcommand*\sphinxAtStartPar{\nobreak\hskip\z@skip}
% No need for the \hspace{0pt} trick (\hskip\z@skip) with luatex
\ifdefined\directlua\let\sphinxAtStartPar\@empty\fi
% user interface: options can be changed midway in a document!
\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}}


%% PASS OPTIONS
%
\input{sphinxlatexoptionhandling.sty}
% pass options to hyperref; it must not have been loaded already
\input{sphinxoptionshyperref.sty}
% pass options to geometry; it must not have been loaded already
\input{sphinxoptionsgeometry.sty}


%% LISTS
%% COLOR (general)
%
\input{sphinxlatexmisclists.sty}


%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
% FIXME: these two should be deprecated
%
\input{sphinxlatexenvindbibtoc.sty}
% FIXME: \normalcolor should be used and \py@NormalColor never defined
\def\py@NormalColor{\color{black}}
% FIXME: \color{TitleColor} should be used directly and \py@TitleColor
% should never get defined.
\def\py@TitleColor{\color{TitleColor}}


%% FIXME STUFF
%
\input{sphinxlatexmiscfixme.sty}


%% PAGE STYLING
%% PACKAGES
%
\input{sphinxlatexstylepage.sty}


%% TITLES
% as will be indicated below, secondary style files load some more packages
%
\input{sphinxlatexstyleheadings.sty}
% for \text macro and \iffirstchoice@ conditional even if amsmath not loaded
\RequirePackage{amstext}
% it was passed "warn" option from latex template
\RequirePackage{textcomp}
% For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code
% for allowing figures in tables.
\RequirePackage{float}
% For floating figures in the text. Better to load after float.
\RequirePackage{wrapfig}
% control caption around literal-block
\RequirePackage{capt-of}
\RequirePackage{needspace}
% support hlist directive
\RequirePackage{multicol}


%% GRAPHICS
%
\RequirePackage{graphicx}
\input{sphinxlatexgraphics.sty}


%% CITATIONS
%% FRAMED ENVIRONMENTS
% For framing code-blocks and warning type notices, and shadowing topics
\RequirePackage{framed}
%
\protected\def\sphinxcite{\cite}
% macros and environment for display literals (sphinxVerbatim, sphinxalltt)
% and inline literals (\sphinxupquote); also defines \sphinxhref.
% Requires: fancyvrb, alltt, upquote
\input{sphinxlatexliterals.sty}
%
% topic and contents boxes: sphinxShadowBox uses framed.sty
\input{sphinxlatexshadowbox.sty}
%
% notices and admonitions: sphinxheavybox uses again framed.sty
\input{sphinxlatexadmonitions.sty}


%% FOOTNOTES
%% PYGMENTS
% stylesheet for highlighting with pygments
\RequirePackage{sphinxhighlight}
% fix baseline increase from Pygments latex formatter in case of error tokens
% and keep \fboxsep's scope local via added braces
\def\PYG@tok@err{%
\def\PYG@bc##1{{\setlength{\fboxsep}{-\fboxrule}%
\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}%
}
\def\PYG@tok@cs{%
\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}%
\def\PYG@bc##1{{\setlength{\fboxsep}{0pt}%
\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}%
}%


%% TABLES
%
% Support large numbered footnotes in minipage
% But now obsolete due to systematic use of \savenotes/\spewnotes
% when minipages are in use in the various macro definitions next.
\def\thempfootnote{\arabic{mpfootnote}}
% Requires: tabulary, longtable, varwidth
% extends tabulary and longtable via patches and custom macros to support
% merged cells possibly containing code-blocks in complex tables
\input{sphinxlatextables.sty}


%% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
%
\input{sphinxlatexmiscnumbering.sty}
% Requires: remreset (old LaTeX only)
% relates to numfig and numfig_secnum_depth configuration variables
\input{sphinxlatexnumfig.sty}


%% LITERAL BLOCKS
%% LISTS
%
\input{sphinxlatexenvliteral.sty}
% optionally extends LaTeX maximal list nesting depth and provides
% \sphinxsetlistlabels macro used in mark-up
\input{sphinxlatexlists.sty}


%% TOPIC AND CONTENTS BOXES
%% FOOTNOTES
%
\input{sphinxlatexenvshadowbox.sty}
% support large numbered footnotes in minipage; but this is now obsolete
% from systematic use of savenotes environment around minipages
\def\thempfootnote{\arabic{mpfootnote}}
% this package provides savenotes environment (aka \savenotes/spewnotes)
% For hyperlinked footnotes in tables; also for gathering footnotes from
% topic and warning blocks. Also to allow code-blocks in footnotes.
% Based on footnotehyper, extended to support tabulary multipass system
\RequirePackage{sphinxpackagefootnote}


%% NOTICES AND ADMONITIONS
%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
%
\input{sphinxlatexenvadmonitions.sty}
% requires makeidx
\input{sphinxlatexindbibtoc.sty}


%% PYTHON DOCS MACROS AND ENVIRONMENTS
%% STYLING
%
\input{sphinxlatexenvdocs.sty}
% page
% requires parskip (legacy version) and, except if memoir class, fancyhdr
\input{sphinxlatexstylepage.sty}
% headings
% requires titlesec and, if it is at 2.10.1, etoolbox to patch it
\input{sphinxlatexstyleheadings.sty}
% many \sphinx... prefixed commands to style text
\input{sphinxlatexstyletext.sty}


%% TEXT STYLING
%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
%
\input{sphinxlatexstyletext.sty}
% this legacy code has remained very stable over the years
% (fulllineitems was updated to support multiline signatures)
\input{sphinxlatexobjects.sty}


% FIXME: this line should be dropped, as "9" is default anyhow.
\ifdefined\pdfcompresslevel\pdfcompresslevel = 9 \fi


\endinput
4 changes: 2 additions & 2 deletions ...x/texinputs/sphinxlatexenvadmonitions.sty → sphinx/texinputs/sphinxlatexadmonitions.sty
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
%% NOTICES AND ADMONITIONS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexenvadmonitions.sty}[2021/01/27 admonitions]
\ProvidesFile{sphinxlatexadmonitions.sty}[2021/01/27 admonitions]

% Some are quite plain
% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
Expand Down Expand Up @@ -119,4 +119,4 @@
% workaround some LaTeX "feature" of \end command
{\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}

\endinput
\endinput
9 changes: 7 additions & 2 deletions sphinx/texinputs/sphinxlatexenvindbibtoc.sty → sphinx/texinputs/sphinxlatexindbibtoc.sty
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexenvindbibtoc.sty}[2021/01/27 index, bib., toc]
\ProvidesFile{sphinxlatexindbibtoc.sty}[2021/01/27 index, bib., toc]

\RequirePackage{makeidx}

% fix the double index and bibliography on the table of contents
% in jsclasses (Japanese standard document classes)
Expand Down Expand Up @@ -44,4 +46,7 @@
\newcommand*{\sphinxsymbolsname}{}
\newcommand*{\sphinxnumbersname}{}

\endinput
\protected\def\sphinxcite{\cite}


\endinput
2 changes: 1 addition & 1 deletion sphinx/texinputs/sphinxlatexmisclists.sty → sphinx/texinputs/sphinxlatexlists.sty
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
%% ALPHANUMERIC LIST ITEMS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexmisclists.sty}[2021/01/27 lists]
\ProvidesFile{sphinxlatexlists.sty}[2021/01/27 lists]

\newcommand\sphinxsetlistlabels[5]
{% #1 = style, #2 = enum, #3 = enumnext, #4 = prefix, #5 = suffix
Expand Down
Loading

0 comments on commit 0c0be64

Please sign in to comment.