1% 2% sphinx.sty 3% 4% Adapted from the old python.sty, mostly written by Fred Drake, 5% by Georg Brandl. 6% 7 8\NeedsTeXFormat{LaTeX2e}[1995/12/01] 9\ProvidesPackage{sphinx}[2021/01/27 v4.0.0 LaTeX package (Sphinx markup)] 10 11% provides \ltx@ifundefined 12% (many packages load ltxcmds: graphicx does for pdftex and lualatex but 13% not xelatex, and anyhow kvoptions does, but it may be needed in future to 14% use \sphinxdeprecationwarning earlier, and it needs \ltx@ifundefined) 15\RequirePackage{ltxcmds} 16 17%% for deprecation warnings 18\newcommand\sphinxdeprecationwarning[4]{% #1 the deprecated macro or name, 19% #2 = when deprecated, #3 = when removed, #4 = additional info 20 \edef\spx@tempa{\detokenize{#1}}% 21 \ltx@ifundefined{sphinx_depr_\spx@tempa}{% 22 \global\expandafter\let\csname sphinx_depr_\spx@tempa\endcsname\spx@tempa 23 \expandafter\AtEndDocument\expandafter{\expandafter\let\expandafter 24 \sphinxdeprecatedmacro\csname sphinx_depr_\spx@tempa\endcsname 25 \PackageWarningNoLine{sphinx}{^^J**** SPHINX DEPRECATION WARNING:^^J 26 \sphinxdeprecatedmacro^^J 27 \@spaces- is deprecated at Sphinx #2^^J 28 \@spaces- and removed at Sphinx #3.^^J 29 #4^^J****}}% 30 }{% warning already emitted (at end of latex log), don't repeat 31 }} 32 33 34%% OPTION HANDLING 35% 36 37% We first handle options then load packages, but we need \definecolor from 38% xcolor/color. 39 40% FIXME: we should \RequirePackage{xcolor} always now 41% The xcolor package draws better fcolorboxes around verbatim code 42\IfFileExists{xcolor.sty}{ 43 \RequirePackage{xcolor} 44}{ 45 \RequirePackage{color} 46} 47 48% Handle options via "kvoptions" (later loaded by hyperref anyhow) 49\RequirePackage{kvoptions} 50\SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix 51 52% Sphinx legacy text layout: 1in margins on all four sides 53\ifx\@jsc@uplatextrue\@undefined 54\DeclareStringOption[1in]{hmargin} 55\DeclareStringOption[1in]{vmargin} 56\DeclareStringOption[.5in]{marginpar} 57\else 58% Japanese standard document classes handle \mag in a special way 59\DeclareStringOption[\inv@mag in]{hmargin} 60\DeclareStringOption[\inv@mag in]{vmargin} 61\DeclareStringOption[.5\dimexpr\inv@mag in\relax]{marginpar} 62\fi 63 64\DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0} 65\DeclareStringOption[-1]{numfigreset} 66\DeclareBoolOption[false]{nonumfigreset} 67\DeclareBoolOption[false]{mathnumfig} 68\define@key{sphinx}{bookmarksdepth}{\AtBeginDocument{\hypersetup{bookmarksdepth=#1}}} 69\AtBeginDocument{\define@key{sphinx}{bookmarksdepth}{\hypersetup{bookmarksdepth=#1}}} 70% \DeclareBoolOption[false]{usespart}% not used 71% dimensions, we declare the \dimen registers here. 72\newdimen\sphinxverbatimsep 73\newdimen\sphinxverbatimborder 74\newdimen\sphinxshadowsep 75\newdimen\sphinxshadowsize 76\newdimen\sphinxshadowrule 77% \DeclareStringOption is not convenient for the handling of these dimensions 78% because we want to assign the values to the corresponding registers. Even if 79% we added the code to the key handler it would be too late for the initial 80% set-up and we would need to do initial assignments explicitly. We end up 81% using \define@key directly. 82% verbatim 83\sphinxverbatimsep=\fboxsep 84 \define@key{sphinx}{verbatimsep}{\sphinxverbatimsep\dimexpr #1\relax} 85\sphinxverbatimborder=\fboxrule 86 \define@key{sphinx}{verbatimborder}{\sphinxverbatimborder\dimexpr #1\relax} 87% topic boxes 88\sphinxshadowsep =5pt 89 \define@key{sphinx}{shadowsep}{\sphinxshadowsep\dimexpr #1\relax} 90\sphinxshadowsize=4pt 91 \define@key{sphinx}{shadowsize}{\sphinxshadowsize\dimexpr #1\relax} 92\sphinxshadowrule=\fboxrule 93 \define@key{sphinx}{shadowrule}{\sphinxshadowrule\dimexpr #1\relax} 94% verbatim 95\DeclareBoolOption[true]{verbatimwithframe} 96\DeclareBoolOption[true]{verbatimwrapslines} 97\DeclareBoolOption[false]{verbatimforcewraps} 98\DeclareStringOption[3]{verbatimmaxoverfull} 99\DeclareStringOption[100]{verbatimmaxunderfull} 100\DeclareBoolOption[true]{verbatimhintsturnover} 101\DeclareBoolOption[true]{inlineliteralwraps} 102\DeclareStringOption[t]{literalblockcappos} 103\DeclareStringOption[r]{verbatimcontinuedalign} 104\DeclareStringOption[r]{verbatimcontinuesalign} 105% parsed literal 106\DeclareBoolOption[true]{parsedliteralwraps} 107% \textvisiblespace for compatibility with fontspec+XeTeX/LuaTeX 108\DeclareStringOption[\textcolor{red}{\textvisiblespace}]{verbatimvisiblespace} 109\DeclareStringOption % must use braces to hide the brackets 110 [{\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\m@th\hookrightarrow$}}}]% 111 {verbatimcontinued} 112% notices/admonitions 113% the dimensions for notices/admonitions are kept as macros and assigned to 114% \spx@notice@border at time of use, hence \DeclareStringOption is ok for this 115\newdimen\spx@notice@border 116\DeclareStringOption[0.5pt]{noteborder} 117\DeclareStringOption[0.5pt]{hintborder} 118\DeclareStringOption[0.5pt]{importantborder} 119\DeclareStringOption[0.5pt]{tipborder} 120\DeclareStringOption[1pt]{warningborder} 121\DeclareStringOption[1pt]{cautionborder} 122\DeclareStringOption[1pt]{attentionborder} 123\DeclareStringOption[1pt]{dangerborder} 124\DeclareStringOption[1pt]{errorborder} 125% footnotes 126\DeclareStringOption[\mbox{ }]{AtStartFootnote} 127% we need a public macro name for direct use in latex file 128\newcommand*{\sphinxAtStartFootnote}{\spx@opt@AtStartFootnote} 129% no such need for this one, as it is used inside other macros 130\DeclareStringOption[\leavevmode\unskip]{BeforeFootnote} 131% some font styling. 132\DeclareStringOption[\sffamily\bfseries]{HeaderFamily} 133% colours 134% same problems as for dimensions: we want the key handler to use \definecolor. 135% first, some colours with no prefix, for backwards compatibility 136\newcommand*{\sphinxDeclareColorOption}[2]{% 137 \definecolor{#1}#2% 138 \define@key{sphinx}{#1}{\definecolor{#1}##1}% 139}% 140\sphinxDeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}} 141\sphinxDeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}} 142\sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}} 143\sphinxDeclareColorOption{VerbatimColor}{{rgb}{1,1,1}} 144\sphinxDeclareColorOption{VerbatimBorderColor}{{rgb}{0,0,0}} 145% now the colours defined with "sphinx" prefix in their names 146\newcommand*{\sphinxDeclareSphinxColorOption}[2]{% 147 % set the initial default 148 \definecolor{sphinx#1}#2% 149 % set the key handler. The "value" ##1 must be acceptable by \definecolor. 150 \define@key{sphinx}{#1}{\definecolor{sphinx#1}##1}% 151}% 152% Default color chosen to be as in minted.sty LaTeX package! 153\sphinxDeclareSphinxColorOption{VerbatimHighlightColor}{{rgb}{0.878,1,1}} 154% admonition boxes, "light" style 155\sphinxDeclareSphinxColorOption{noteBorderColor}{{rgb}{0,0,0}} 156\sphinxDeclareSphinxColorOption{hintBorderColor}{{rgb}{0,0,0}} 157\sphinxDeclareSphinxColorOption{importantBorderColor}{{rgb}{0,0,0}} 158\sphinxDeclareSphinxColorOption{tipBorderColor}{{rgb}{0,0,0}} 159% admonition boxes, "heavy" style 160\sphinxDeclareSphinxColorOption{warningBorderColor}{{rgb}{0,0,0}} 161\sphinxDeclareSphinxColorOption{cautionBorderColor}{{rgb}{0,0,0}} 162\sphinxDeclareSphinxColorOption{attentionBorderColor}{{rgb}{0,0,0}} 163\sphinxDeclareSphinxColorOption{dangerBorderColor}{{rgb}{0,0,0}} 164\sphinxDeclareSphinxColorOption{errorBorderColor}{{rgb}{0,0,0}} 165\sphinxDeclareSphinxColorOption{warningBgColor}{{rgb}{1,1,1}} 166\sphinxDeclareSphinxColorOption{cautionBgColor}{{rgb}{1,1,1}} 167\sphinxDeclareSphinxColorOption{attentionBgColor}{{rgb}{1,1,1}} 168\sphinxDeclareSphinxColorOption{dangerBgColor}{{rgb}{1,1,1}} 169\sphinxDeclareSphinxColorOption{errorBgColor}{{rgb}{1,1,1}} 170 171\DeclareDefaultOption{\@unknownoptionerror} 172\ProcessKeyvalOptions* 173% don't allow use of maxlistdepth via \sphinxsetup. 174\DisableKeyvalOption{sphinx}{maxlistdepth} 175\DisableKeyvalOption{sphinx}{numfigreset} 176\DisableKeyvalOption{sphinx}{nonumfigreset} 177\DisableKeyvalOption{sphinx}{mathnumfig} 178% FIXME: this is unrelated to an option, move this elsewhere 179% To allow hyphenation of first word in narrow contexts; no option, 180% customization to be done via 'preamble' key 181\newcommand*\sphinxAtStartPar{\leavevmode\nobreak\hskip\z@skip} 182% No need for the \hspace{0pt} trick (\hskip\z@skip) with luatex 183\ifdefined\directlua\let\sphinxAtStartPar\@empty\fi 184% user interface: options can be changed midway in a document! 185\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}} 186 187 188%% MISCELLANEOUS CONTEXT 189% 190% flag to be set in a framed environment 191% (defined here as currently needed by three sphinxlatex....sty files and 192% even if not needed if such files are replaced, the definition does no harm) 193\newif\ifspx@inframed 194% 195% \spx@ifcaptionpackage (defined at begin document) 196% is needed currently in macros from: 197% sphinxlatexliterals.sty (sphinxVerbatim) 198% sphinxlatextables.sty (for some macros used in the table templates) 199% 200% \sphinxcaption is mark-up injected by the tabular and tabulary templates 201% it is defined in sphinxlatextables.sty 202% 203% store the original \caption macro for usage with figures inside longtable 204% and tabulary cells. Make sure we get the final \caption in presence of 205% caption package, whether the latter was loaded before or after sphinx. 206\AtBeginDocument{% 207 \let\spx@originalcaption\caption 208 \@ifpackageloaded{caption} 209 {\let\spx@ifcaptionpackage\@firstoftwo 210 \caption@AtBeginDocument*{\let\spx@originalcaption\caption}% 211% in presence of caption package, drop our own \sphinxcaption whose aim was to 212% ensure same width of caption to all kinds of tables (tabular(y), longtable), 213% because caption package has its own width (or margin) option 214 \def\sphinxcaption{\caption}% 215 }% 216 {\let\spx@ifcaptionpackage\@secondoftwo}% 217} 218 219%% PASS OPTIONS 220% 221% pass options to hyperref; it must not have been loaded already 222\input{sphinxoptionshyperref.sty} 223% pass options to geometry; it must not have been loaded already 224\input{sphinxoptionsgeometry.sty} 225 226 227%% COLOR (general) 228% 229% FIXME: these two should be deprecated 230% 231% FIXME: \normalcolor should be used and \py@NormalColor never defined 232\def\py@NormalColor{\color{black}} 233% FIXME: \color{TitleColor} should be used directly and \py@TitleColor 234% should never get defined. 235\def\py@TitleColor{\color{TitleColor}} 236 237 238%% PACKAGES 239% 240% as will be indicated below, secondary style files load some more packages 241% 242% For \text macro (sphinx.util.texescape) 243% also for usage of \firstchoice@true(false) in sphinxlatexgraphics.sty 244\RequirePackage{amstext} 245% It was passed "warn" option from latex template in case it is already loaded 246% via some other package before \usepackage{sphinx} in preamble 247\RequirePackage{textcomp} 248% For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code 249% for allowing figures in tables. 250\RequirePackage{float} 251% For floating figures in the text. Better to load after float. 252\RequirePackage{wrapfig} 253% Provides \captionof, used once by latex writer (\captionof{figure}) 254\RequirePackage{capt-of} 255% Support hlist directive 256\RequirePackage{multicol} 257 258 259%% GRAPHICS 260% 261% It will always be needed, so let's load it here 262\RequirePackage{graphicx} 263\input{sphinxlatexgraphics.sty} 264 265 266%% FRAMED ENVIRONMENTS 267% 268\input{sphinxlatexadmonitions.sty} 269\input{sphinxlatexliterals.sty} 270\input{sphinxlatexshadowbox.sty} 271 272 273%% CONTAINERS 274% 275\input{sphinxlatexcontainers.sty} 276 277 278%% PYGMENTS 279% stylesheet for highlighting with pygments 280\RequirePackage{sphinxhighlight} 281 282 283%% TABLES 284% 285\input{sphinxlatextables.sty} 286 287 288%% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS 289% 290\input{sphinxlatexnumfig.sty} 291 292 293%% LISTS 294% 295\input{sphinxlatexlists.sty} 296 297 298%% FOOTNOTES 299% 300% Support scopes for footnote numbering 301\newcounter{sphinxscope} 302\newcommand{\sphinxstepscope}{\stepcounter{sphinxscope}} 303% Explicitly numbered footnotes may be referred to, and for this to be 304% clickable we need to have only one target. So we will step this at each 305% explicit footnote and let \thesphinxscope take it into account 306\newcounter{sphinxexplicit} 307\newcommand{\sphinxstepexplicit}{\stepcounter{sphinxexplicit}} 308% Some babel/polyglossia languages fiddle with \@arabic, so let's be extra 309% cautious and redefine \thesphinxscope with \number not \@arabic. 310% Memo: we expect some subtle redefinition of \thesphinxscope to be a part of page 311% scoping for footnotes, when we shall implement it. 312\renewcommand{\thesphinxscope}{\number\value{sphinxscope}.\number\value{sphinxexplicit}} 313\newcommand\sphinxthefootnotemark[2]{% 314 % this is used to make reference to an explicitly numbered footnote not on same page 315 % #1=label of footnote text, #2=page number where footnote text was printed 316 \ifdefined\pagename 317 \pagename\space#2, % <- space 318 \else 319 p. #2, % <- space 320 \fi #1% no space 321} 322% support large numbered footnotes in minipage; but this is now obsolete 323% from systematic use of savenotes environment around minipages 324\def\thempfootnote{\arabic{mpfootnote}} 325% This package is needed to support hyperlinked footnotes in tables and 326% framed contents, and to allow code-blocks in footnotes. 327\RequirePackage{sphinxpackagefootnote} 328 329 330%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS 331% 332\input{sphinxlatexindbibtoc.sty} 333 334 335%% STYLING 336% 337\input{sphinxlatexstylepage.sty} 338\input{sphinxlatexstyleheadings.sty} 339\input{sphinxlatexstyletext.sty} 340 341 342%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS 343% 344\input{sphinxlatexobjects.sty} 345 346 347% FIXME: this line should be dropped, as "9" is default anyhow. 348\ifdefined\pdfcompresslevel\pdfcompresslevel = 9 \fi 349 350 351\endinput 352