diff options
Diffstat (limited to 'sphinx/texinputs/sphinx.sty')
| -rw-r--r-- | sphinx/texinputs/sphinx.sty | 881 |
1 files changed, 560 insertions, 321 deletions
diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index d025a0797..b89ffa64e 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -6,38 +6,22 @@ % \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2010/01/15 LaTeX package (Sphinx markup)] +\ProvidesPackage{sphinx}[2016/10/29 v1.5 LaTeX package (Sphinx markup)] -% this is the \ltx@ifundefined of ltxcmds.sty, which is loaded by -% hyperref.sty, but we need it before, and initial ltxcmds.sty -% as in TL2009/Debian had wrong definition. -\newcommand{\spx@ifundefined}[1]{% - \ifcsname #1\endcsname - \expandafter\ifx\csname #1\endcsname\relax - \expandafter\expandafter\expandafter\@firstoftwo - \else - \expandafter\expandafter\expandafter\@secondoftwo - \fi - \else - \expandafter\@firstoftwo - \fi -} +% we delay handling of options to after having loaded packages, because +% of the need to use \definecolor. +\RequirePackage{graphicx} \@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}} % for \text macro and \iffirstchoice@ conditional even if amsmath not loaded \RequirePackage{amstext} \RequirePackage{textcomp} -% fancybox not used anymore and will be removed at Sphinx-1.5 -\RequirePackage{fancybox} \RequirePackage{titlesec} \RequirePackage{tabulary} \RequirePackage{makeidx} % For framing code-blocks and warning type notices, and shadowing topics \RequirePackage{framed} -\newif\ifspx@inframed % flag set if we are in a framed environment -% ifthen not used anymore and will be removed at Sphinx-1.5 -\RequirePackage{ifthen} % The xcolor package draws better fcolorboxes around verbatim code \IfFileExists{xcolor.sty}{ \RequirePackage{xcolor} @@ -46,12 +30,20 @@ } % For highlighted code. \RequirePackage{fancyvrb} +\fvset{fontsize=\small} % For table captions. \RequirePackage{threeparttable} -% Handle footnotes in tables. -\RequirePackage{footnote} +% For hyperlinked footnotes in tables; also for gathering footnotes from +% topic and warning blocks. Also to allow code-blocks in footnotes. +\RequirePackage{footnotehyper-sphinx} \makesavenoteenv{tabulary} -% For floating figures in the text. +\makesavenoteenv{tabular} +\makesavenoteenv{threeparttable} +% (longtable is hyperref compatible and needs no special treatment here.) +% 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} % Separate paragraphs by space by default. \RequirePackage{parskip} @@ -59,33 +51,131 @@ \RequirePackage{alltt} % Display "real" single quotes in literal blocks. \RequirePackage{upquote} -% For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code -% for allowing figures in tables. -\RequirePackage{float} -% Redefine these colors to your liking in the preamble. -\definecolor{TitleColor}{rgb}{0.126,0.263,0.361} -\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486} -\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388} -% Redefine these colors to something if you want to have colored -% background and border for code examples. -\definecolor{VerbatimColor}{rgb}{1,1,1} -\definecolor{VerbatimBorderColor}{rgb}{0,0,0} - -% Uncomment these two lines to ignore the paper size and make the page -% size more like a typical published manual. -%\renewcommand{\paperheight}{9in} -%\renewcommand{\paperwidth}{8.5in} % typical squarish manual -%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python'' +% Handle options via "kvoptions" (later loaded by hyperref anyhow) +\RequirePackage{kvoptions} +\SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix + +\DeclareBoolOption{dontkeepoldnames} % \ifspx@opt@dontkeepoldnames = \iffalse +\DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0} + +% 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]{inlineliteralwraps} +% \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}% +}% +% 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} +% user interface: options can be changed midway in a document! +\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}} +% this is the \ltx@ifundefined of ltxcmds.sty, which is loaded by +% hyperref.sty, but we need it before, and the first release of +% ltxcmds.sty as in TL2009/Debian has wrong definition. +\newcommand{\spx@ifundefined}[1]{% + \ifcsname #1\endcsname + \expandafter\ifx\csname #1\endcsname\relax + \expandafter\expandafter\expandafter\@firstoftwo + \else + \expandafter\expandafter\expandafter\@secondoftwo + \fi + \else + \expandafter\@firstoftwo + \fi +} +% FIXME: the reasons might be obsolete (better color drivers now?) % use pdfoutput for pTeX and dvipdfmx % when pTeX (\kanjiskip is defined), set pdfoutput to evade \include{pdfcolor} \ifx\kanjiskip\undefined\else \newcount\pdfoutput\pdfoutput=0 \fi -\RequirePackage{graphicx} - % for PDF output, use colors and maximal compression \newif\ifsphinxpdfoutput % used in \maketitle \ifx\pdfoutput\undefined\else @@ -107,24 +197,6 @@ \def\py@TitleColor{\color{TitleColor}} \fi -% Increase printable page size (copied from fullpage.sty) -\topmargin 0pt -\advance \topmargin by -\headheight -\advance \topmargin by -\headsep - -% attempt to work a little better for A4 users -\textheight \paperheight -\advance\textheight by -2in - -\oddsidemargin 0pt -\evensidemargin 0pt -%\evensidemargin -.25in % for ``manual size'' documents -\marginparwidth 0.5in - -\textwidth \paperwidth -\advance\textwidth by -2in - - % Style parameters and macros used by most documents here \raggedbottom \sloppy @@ -133,8 +205,7 @@ \pagestyle{empty} % start this way % Use this to set the font family for headers and other decor: -\newcommand{\py@HeaderFamily}{\sffamily\bfseries} -\newcommand{\sphinxSetHeaderFamily}[1]{\renewcommand{\py@HeaderFamily}{#1}} +\newcommand{\py@HeaderFamily}{\spx@opt@HeaderFamily} % Redefine the 'normal' header/footer style when using "fancyhdr" package: \spx@ifundefined{fancyhf}{}{ @@ -163,32 +234,61 @@ } % Some custom font markup commands. -% *** the macros without \sphinx prefix are still defined at bottom of file *** -\newcommand{\sphinxstrong}[1]{{\textbf{#1}}} -% let \sphinxcode and \sphinxbfcode use straight quotes. \@noligs patched by upquote, -% but needs protection in "moving arguments" such as for captions. -% Use \scantokens to handle e.g. \item[{\sphinxcode{'fontenc'}}] -\DeclareRobustCommand{\sphinxcode}[1]{{\@noligs\scantokens{\texttt{#1}\relax}}} -\newcommand{\sphinxbfcode}[1]{\sphinxcode{\bfseries#1}} -\newcommand{\sphinxemail}[1]{\textsf{#1}} -\newcommand{\sphinxtablecontinued}[1]{\textsf{#1}} -\newcommand{\sphinxtitleref}[1]{\emph{#1}} -\newcommand{\sphinxmenuselection}[1]{\emph{#1}} -\newcommand{\sphinxaccelerator}[1]{\underline{#1}} -\newcommand{\sphinxcrossref}[1]{\emph{#1}} -\newcommand{\sphinxtermref}[1]{\emph{#1}} - -% miscellaneous related to footnotes -\newcommand*{\sphinxAtStartFootnote}{\mbox{ }} -% Support large numbered footnotes in minipage (cf. admonitions) +% *** the macros without \sphinx prefix are still defined near end of file *** +\long\protected\def\sphinxstrong#1{{\textbf{#1}}} +% to obtain straight quotes we execute \@noligs as patched by upquote, and +% \scantokens is needed in cases where it would be too late for the macro to +% first set catcodes and then fetch its argument. We also make the contents +% breakable at non-escaped . , ; ? ! / using \sphinxbreaksviaactive. +% the macro must be protected if it ends up used in moving arguments, +% in 'alltt' \@noligs is done already, and the \scantokens must be avoided. +\long\protected\def\sphinxcode#1{{\def\@tempa{alltt}% + \ifx\@tempa\@currenvir\else + \ifspx@opt@inlineliteralwraps + \sphinxbreaksviaactive\let\sphinxafterbreak\empty + % do not overwrite the comma set-up + \let\verbatim@nolig@list\sphinx@literal@nolig@list + \fi + % fix a space-gobbling issue due to LaTeX's original \do@noligs + \let\do@noligs\sphinx@do@noligs + \@noligs\endlinechar\m@ne\everyeof{\noexpand}% + \expandafter\scantokens + \fi {\texttt{#1}}}} +\def\sphinx@do@noligs #1{\catcode`#1\active\begingroup\lccode`\~`#1\relax + \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1 }}} +\def\sphinx@literal@nolig@list {\do\`\do\<\do\>\do\'\do\-}% + +\long\protected\def\sphinxbfcode#1{\sphinxcode{\bfseries#1}} +\long\protected\def\sphinxemail#1{\textsf{#1}} +\long\protected\def\sphinxtablecontinued#1{\textsf{#1}} +\long\protected\def\sphinxtitleref#1{\emph{#1}} +\long\protected\def\sphinxmenuselection#1{\emph{#1}} +\long\protected\def\sphinxaccelerator#1{\underline{#1}} +\long\protected\def\sphinxcrossref#1{\emph{#1}} +\long\protected\def\sphinxtermref#1{\emph{#1}} + +% 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}} -% Redefine the Verbatim environment to allow border and background colors -% and to handle the top caption in a non separable by pagebreak way. -% The original environment is still used for verbatims within tables. -\let\OriginalVerbatim=\Verbatim -\let\endOriginalVerbatim=\endVerbatim +% Code-blocks +% Based on use of "fancyvrb.sty"'s Verbatim. +% - with framing allowing page breaks ("framed.sty") +% - with breaking of long lines (exploits Pygments mark-up), +% - with possibly of a top caption, non-separable by pagebreak. +% - and usable inside tables or footnotes ("footnotehyper-sphinx"). + +% For maintaining compatibility with Sphinx < 1.5, we define and use these +% when (unmodified) Verbatim will be needed. But Sphinx >= 1.5 does not modify +% original Verbatim anyhow. +\let\OriginalVerbatim \Verbatim +\let\endOriginalVerbatim\endVerbatim + +\newif\ifspx@inframed % flag set if we are already in a framed environment +% if forced use of minipage encapsulation is needed (e.g. table cells) +\newif\ifsphinxverbatimwithminipage \sphinxverbatimwithminipagefalse \newcommand\spx@colorbox [2]{% % #1 will be \fcolorbox or, for first part of frame: \spx@fcolorbox % let the framing obey the current indentation (adapted from framed.sty's code). @@ -202,12 +302,14 @@ \def\spx@fcolorbox #1#2% {\color@b@x {\fboxsep\z@\color{#1}\spx@VerbatimFBox}{\color{#2}}}% -% The title is specified from outside as macro \sphinxVerbatimTitle. +% The title (caption) is specified from outside as macro \sphinxVerbatimTitle. % \sphinxVerbatimTitle is reset to empty after each use of Verbatim. \newcommand*\sphinxVerbatimTitle {} +% This box to typeset the caption before framed.sty multiple passes for framing. +\newbox\spx@VerbatimTitleBox % Holder macro for labels of literal blocks. Set-up by LaTeX writer. \newcommand*\sphinxLiteralBlockLabel {} -\newcommand*\sphinxSetupCaptionForVerbatim [2] +\newcommand*\sphinxSetupCaptionForVerbatim [1] {% \needspace{\sphinxliteralblockneedspace}% % insert a \label via \sphinxLiteralBlockLabel @@ -215,31 +317,31 @@ % the caption inserts \abovecaptionskip whitespace above itself (usually 10pt) % there is also \belowcaptionskip but it is usually zero, hence the \smallskip \def\sphinxVerbatimTitle - {\py@NormalColor\captionof{#1}{\sphinxLiteralBlockLabel #2}\smallskip }% + {\py@NormalColor + \captionof{literalblock}{\sphinxLiteralBlockLabel #1}\smallskip }% } +\newcommand*\sphinxSetupCodeBlockInFootnote {% + \fvset{fontsize=\footnotesize}\let\caption\sphinxfigcaption + \sphinxverbatimwithminipagetrue % reduces vertical spaces + % we counteract float.sty's \caption which does \@normalsize + \let\normalsize\footnotesize\let\@parboxrestore\relax + \abovecaptionskip \smallskipamount \belowcaptionskip \z@skip} % Inspired and adapted from framed.sty's \CustomFBox with extra handling -% of a non separable by pagebreak caption, and controlled counter stepping. -\newif\ifspx@myfirstframedpass +% of a non separable by pagebreak caption. \long\def\spx@VerbatimFBox#1{% \leavevmode \begingroup - % framed.sty does some measuring but this macro adds possibly a caption - % use amsmath conditional to inhibit the caption counter stepping after - % first pass - \ifspx@myfirstframedpass\else\firstchoice@false\fi \setbox\@tempboxa\hbox{\kern\fboxsep{#1}\kern\fboxsep}% \hbox {\lower\dimexpr\fboxrule+\fboxsep+\dp\@tempboxa \hbox{% - \vbox{\ifx\sphinxVerbatimTitle\empty\else + \vbox{\ifvoid\spx@VerbatimTitleBox\else % add the caption in a centered way above possibly indented frame % hide its width from framed.sty's measuring step % note that the caption brings \abovecaptionskip top vertical space \moveright\dimexpr\fboxrule+.5\wd\@tempboxa - \hb@xt@\z@{\hss\begin{minipage}{\wd\@tempboxa}% - \sphinxVerbatimTitle - \end{minipage}\hss}\fi + \hb@xt@\z@{\hss\unhcopy\spx@VerbatimTitleBox\hss}\fi % draw frame border _latest_ to avoid pdf viewer issue \kern\fboxrule \hbox{\kern\fboxrule @@ -255,63 +357,60 @@ \hrule\@height\fboxrule}% }}% \endgroup - \global\spx@myfirstframedpassfalse } % For linebreaks inside Verbatim environment from package fancyvrb. \newbox\sphinxcontinuationbox \newbox\sphinxvisiblespacebox -% These are user customizable e.g. from latex_elements's preamble key. -% Use of \textvisiblespace for compatibility with XeTeX/LuaTeX/fontspec. -\newcommand*\sphinxvisiblespace {\textcolor{red}{\textvisiblespace}} -\newcommand*\sphinxcontinuationsymbol {\textcolor{red}{\llap{\tiny$\m@th\hookrightarrow$}}} -\newcommand*\sphinxcontinuationindent {3ex } -\newcommand*\sphinxafterbreak {\kern\sphinxcontinuationindent\copy\sphinxcontinuationbox} +\newcommand*\sphinxafterbreak {\copy\sphinxcontinuationbox} % Take advantage of the already applied Pygments mark-up to insert % potential linebreaks for TeX processing. % {, <, #, %, $, ' and ": go to next line. % _, }, ^, &, >, - and ~: stay at end of broken line. % Use of \textquotesingle for straight quote. +% FIXME: convert this to package options +\newcommand*\sphinxbreaksbeforelist {% + \do\PYGZob\{\do\PYGZlt\<\do\PYGZsh\#\do\PYGZpc\%% {, <, #, %, + \do\PYGZdl\$\do\PYGZdq\"% $, " + \def\PYGZsq + {\discretionary{}{\sphinxafterbreak\textquotesingle}{\textquotesingle}}% ' +} +\newcommand*\sphinxbreaksafterlist {% + \do\PYGZus\_\do\PYGZcb\}\do\PYGZca\^\do\PYGZam\&% _, }, ^, &, + \do\PYGZgt\>\do\PYGZhy\-\do\PYGZti\~% >, -, ~ +} \newcommand*\sphinxbreaksatspecials {% - \def\PYGZus{\discretionary{\char`\_}{\sphinxafterbreak}{\char`\_}}% - \def\PYGZob{\discretionary{}{\sphinxafterbreak\char`\{}{\char`\{}}% - \def\PYGZcb{\discretionary{\char`\}}{\sphinxafterbreak}{\char`\}}}% - \def\PYGZca{\discretionary{\char`\^}{\sphinxafterbreak}{\char`\^}}% - \def\PYGZam{\discretionary{\char`\&}{\sphinxafterbreak}{\char`\&}}% - \def\PYGZlt{\discretionary{}{\sphinxafterbreak\char`\<}{\char`\<}}% - \def\PYGZgt{\discretionary{\char`\>}{\sphinxafterbreak}{\char`\>}}% - \def\PYGZsh{\discretionary{}{\sphinxafterbreak\char`\#}{\char`\#}}% - \def\PYGZpc{\discretionary{}{\sphinxafterbreak\char`\%}{\char`\%}}% - \def\PYGZdl{\discretionary{}{\sphinxafterbreak\char`\$}{\char`\$}}% - \def\PYGZhy{\discretionary{\char`\-}{\sphinxafterbreak}{\char`\-}}% - \def\PYGZsq{\discretionary{}{\sphinxafterbreak\textquotesingle}{\textquotesingle}}% - \def\PYGZdq{\discretionary{}{\sphinxafterbreak\char`\"}{\char`\"}}% - \def\PYGZti{\discretionary{\char`\~}{\sphinxafterbreak}{\char`\~}}% + \def\do##1##2% + {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}% + \sphinxbreaksbeforelist + \def\do##1##2% + {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}% + \sphinxbreaksafterlist } \def\sphinx@verbatim@nolig@list {\do \`}% % Some characters . , ; ? ! / are not pygmentized. % This macro makes them "active" and they will insert potential linebreaks -\newcommand*\sphinxbreaksatpunct {% - \lccode`\~`\.\lowercase{\def~}{\discretionary{\char`\.}{\sphinxafterbreak}{\char`\.}}% - \lccode`\~`\,\lowercase{\def~}{\discretionary{\char`\,}{\sphinxafterbreak}{\char`\,}}% - \lccode`\~`\;\lowercase{\def~}{\discretionary{\char`\;}{\sphinxafterbreak}{\char`\;}}% - \lccode`\~`\:\lowercase{\def~}{\discretionary{\char`\:}{\sphinxafterbreak}{\char`\:}}% - \lccode`\~`\?\lowercase{\def~}{\discretionary{\char`\?}{\sphinxafterbreak}{\char`\?}}% - \lccode`\~`\!\lowercase{\def~}{\discretionary{\char`\!}{\sphinxafterbreak}{\char`\!}}% - \lccode`\~`\/\lowercase{\def~}{\discretionary{\char`\/}{\sphinxafterbreak}{\char`\/}}% - \catcode`\.\active - \catcode`\,\active - \catcode`\;\active - \catcode`\:\active - \catcode`\?\active - \catcode`\!\active - \catcode`\/\active +\newcommand*\sphinxbreaksbeforeactivelist {}% none +\newcommand*\sphinxbreaksafteractivelist {\do\.\do\,\do\;\do\?\do\!\do\/} +\newcommand*\sphinxbreaksviaactive {% + \def\do##1{\lccode`\~`##1% + \lowercase{\def~}{\discretionary{}{\sphinxafterbreak\char`##1}{\char`##1}}% + \catcode`##1\active}% + \sphinxbreaksbeforeactivelist + \def\do##1{\lccode`\~`##1% + \lowercase{\def~}{\discretionary{\char`##1}{\sphinxafterbreak}{\char`##1}}% + \catcode`##1\active}% + \sphinxbreaksafteractivelist \lccode`\~`\~ } -\renewcommand{\Verbatim}[1][1]{% +% needed to create wrapper environments of fancyvrb's Verbatim +\newcommand*{\sphinxVerbatimEnvironment}{\gdef\FV@EnvironName{sphinxVerbatim}} +% Sphinx <1.5 optional argument was in fact mandatory. It is now really +% optional and handled by original Verbatim. +\newenvironment{sphinxVerbatim}{% % quit horizontal mode if we are still in a paragraph \par % list starts new par, but we don't want it to be set apart vertically @@ -327,16 +426,25 @@ \needspace{\sphinxliteralblockwithoutcaptionneedspace}% \phantomsection\sphinxLiteralBlockLabel \fi - \fi + \setbox\spx@VerbatimTitleBox\box\voidb@x + \else % non-empty \sphinxVerbatimTitle has label inside it (in case there is one) + \setbox\spx@VerbatimTitleBox + \hbox{\begin{minipage}{\linewidth}% + \sphinxVerbatimTitle + \end{minipage}}% + \fi + \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder + % setting borderwidth to zero is simplest for no-frame effect with same pagebreaks + \ifspx@opt@verbatimwithframe\else\fboxrule\z@\fi % Customize framed.sty \MakeFramed to glue caption to literal block - \global\spx@myfirstframedpasstrue % via \spx@fcolorbox, will use \spx@VerbatimFBox which inserts title \def\FrameCommand {\spx@colorbox\spx@fcolorbox }% \let\FirstFrameCommand\FrameCommand % for mid pages and last page portion of (long) split frame: \def\MidFrameCommand{\spx@colorbox\fcolorbox }% \let\LastFrameCommand\MidFrameCommand + \ifspx@opt@verbatimwrapslines % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes. % This customization wraps each line from the input in a \vtop, thus % allowing it to wrap and display on two or more lines in the latex output. @@ -345,8 +453,9 @@ % to achieve this without extensive rewrite of fancyvrb. % - The (not used in sphinx) obeytabs option to Verbatim is % broken by this change (showtabs and tabspace work). - \sbox\sphinxcontinuationbox {\sphinxcontinuationsymbol}% - \sbox\sphinxvisiblespacebox {\FV@SetupFont\sphinxvisiblespace}% + \expandafter\def\expandafter\FV@SetupFont\expandafter + {\FV@SetupFont\sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}% + \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}}% \def\FancyVerbFormatLine ##1{\hsize\linewidth \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@ \doublehyphendemerits\z@\finalhyphendemerits\z@ @@ -360,12 +469,15 @@ \discretionary{\copy\sphinxvisiblespacebox}{\sphinxafterbreak} {\kern\fontdimen2\font}% }% - % go around fancyvrb's check of @currenvir (for case of minipage below) - \renewcommand*{\VerbatimEnvironment}{\gdef\FV@EnvironName{Verbatim}}% - % go around fancyvrb's check of current list depth - \def\@toodeep {\advance\@listdepth\@ne}% % Allow breaks at special characters using \PYG... macros. \sphinxbreaksatspecials + % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation) + \def\FancyVerbCodes{\sphinxbreaksviaactive}% + \fi % end of conditional code for wrapping long code lines + % go around fancyvrb's check of \@currenvir + \let\VerbatimEnvironment\sphinxVerbatimEnvironment + % go around fancyvrb's check of current list depth + \def\@toodeep {\advance\@listdepth\@ne}% % The list environment is needed to control perfectly the vertical space. % Note: \OuterFrameSep used by framed.sty is later set to \topsep hence 0pt. % - if caption: vertical space above caption = (\abovecaptionskip + D) with @@ -379,34 +491,48 @@ \rightmargin\z@ \parindent \z@% becomes \itemindent. Default zero, but perhaps overwritten. \trivlist\item\relax - % use a minipage if we are already inside a framed environment + \ifsphinxverbatimwithminipage\spx@inframedtrue\fi + % use a minipage if we are already inside a framed environment \ifspx@inframed\noindent\begin{minipage}{\linewidth}\fi \MakeFramed {% adapted over from framed.sty's snugshade environment - \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize - \@setminipage }% - \small + \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage + }% % For grid placement from \strut's in \FancyVerbFormatLine \lineskip\z@skip - % Breaks at punctuation characters . , ; ? ! and / need catcode=\active - % and the active comma should not be overwritten by \@noligs - \let\verbatim@nolig@list \sphinx@verbatim@nolig@list - \OriginalVerbatim[#1,codes*=\sphinxbreaksatpunct]% + % active comma should not be overwritten by \@noligs + \ifspx@opt@verbatimwrapslines + \let\verbatim@nolig@list \sphinx@verbatim@nolig@list + \fi + % will fetch its optional arguments if any + \OriginalVerbatim } -\renewcommand{\endVerbatim}{% +{% \endOriginalVerbatim - \par\unskip\@minipagefalse\endMakeFramed + \par\unskip\@minipagefalse\endMakeFramed % from framed.sty snugshade \ifspx@inframed\end{minipage}\fi \endtrivlist } - -% define macro to frame contents and add shadow on right and bottom -% use public names for customizable lengths -\newlength\sphinxshadowsep \setlength\sphinxshadowsep {5pt} -\newlength\sphinxshadowsize \setlength\sphinxshadowsize {4pt} -\newlength\sphinxshadowrule -% this uses \fboxrule value at loading time of sphinx.sty (0.4pt normally) -\setlength\sphinxshadowrule {\fboxrule} - +\newenvironment {sphinxVerbatimNoFrame} + {\spx@opt@verbatimwithframefalse + % needed for fancyvrb as literal code will end in \end{sphinxVerbatimNoFrame} + \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimNoFrame}}% + \begin{sphinxVerbatim}} + {\end{sphinxVerbatim}} +\newenvironment {sphinxVerbatimintable} + {% don't use a frame if in a table cell + \spx@opt@verbatimwithframefalse + \sphinxverbatimwithminipagetrue + % counteract longtable redefinition of caption + \let\caption\sphinxfigcaption + % reduce above caption space if in a table cell + \abovecaptionskip\smallskipamount + \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimintable}}% + \begin{sphinxVerbatim}} + {\end{sphinxVerbatim}} + +% Topic boxes + +% Again based on use of "framed.sty", this allows breakable framed boxes. \long\def\spx@ShadowFBox#1{% \leavevmode\begingroup % first we frame the box #1 @@ -451,6 +577,8 @@ % imitate closely the layout from Sphinx <= 1.4.1; the \FrameHeightAdjust % will put top part of frame on this baseline. \def\FrameHeightAdjust {\baselineskip}% + % use package footnote to handle footnotes + \savenotes \trivlist\item\noindent % use a minipage if we are already inside a framed environment \ifspx@inframed\begin{minipage}{\linewidth}\fi @@ -464,9 +592,6 @@ % itemize/enumerate are therein typeset more tightly, we want to keep % that). We copy-paste from LaTeX source code but don't do a real minipage. \@pboxswfalse - % for footnotes, but Sphinx inactivates footnotes in topics - \def\@mpfn{mpfootnote}\def\thempfn{\thempfootnote}\c@mpfootnote\z@ - \let\@footnotetext\@mpfootnotetext \let\@listdepth\@mplistdepth \@mplistdepth\z@ \@minipagerestore \@setminipage @@ -474,14 +599,12 @@ }% {% insert the "endminipage" code \par\unskip - % handle (currently non existing) minipage style footnotes - \ifvoid\@mpfootins\else - \vskip\skip\@mpfootins\normalcolor\footnoterule\unvbox\@mpfootins - \fi \@minipagefalse \endMakeFramed \ifspx@inframed\end{minipage}\fi \endtrivlist + % output the stored footnotes + \spewnotes } @@ -509,13 +632,13 @@ % {fulllineitems} is the main environment for object descriptions. % \newcommand{\py@itemnewline}[1]{% - \@tempdima\linewidth% + \@tempdima\linewidth \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}% } \newenvironment{fulllineitems}{ - \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt - \rightmargin 0pt \topsep -\parskip \partopsep \parskip + \begin{list}{}{\labelwidth \leftmargin \labelsep \z@ + \rightmargin \z@ \topsep -\parskip \partopsep \parskip \itemsep -\parsep \let\makelabel=\py@itemnewline} }{\end{list}} @@ -527,35 +650,71 @@ \newlength{\py@argswidth} \newcommand{\py@sigparams}[2]{% \parbox[t]{\py@argswidth}{#1\sphinxcode{)}#2}} -\newcommand{\pysigline}[1]{\item[#1]\nopagebreak} +\newcommand{\pysigline}[1]{\item[{#1}]\nopagebreak} \newcommand{\pysiglinewithargsret}[3]{% \settowidth{\py@argswidth}{#1\sphinxcode{(}}% \addtolength{\py@argswidth}{-2\py@argswidth}% \addtolength{\py@argswidth}{\linewidth}% - \item[#1\sphinxcode{(}\py@sigparams{#2}{#3}]} + \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]} % Production lists % -\newenvironment{productionlist}{ +\newenvironment{productionlist}{% % \def\sphinxoptional##1{{\Large[}##1{\Large]}} - \def\production##1##2{\\\sphinxcode{##1}&::=&\sphinxcode{##2}} - \def\productioncont##1{\\& &\sphinxcode{##1}} + \def\production##1##2{\\\sphinxcode{##1}&::=&\sphinxcode{##2}}% + \def\productioncont##1{\\& &\sphinxcode{##1}}% \parindent=2em \indent - \setlength{\LTpre}{0pt} - \setlength{\LTpost}{0pt} + \setlength{\LTpre}{0pt}% + \setlength{\LTpost}{0pt}% \begin{longtable}[l]{lcl} }{% \end{longtable} } % Notices / Admonitions -% +% Some are quite plain +% the spx@notice@bordercolor etc are set in the sphinxadmonition environment +\newenvironment{sphinxlightbox}{% + \par\allowbreak + \noindent{\color{spx@notice@bordercolor}% + \rule{\linewidth}{\spx@notice@border}}\par\nobreak + {\parskip\z@skip\noindent}% + } + {% + \par + % counteract previous possible negative skip (French lists!): + % (we can't cancel that any earlier \vskip introduced a potential pagebreak) + \ifdim\lastskip<\z@\vskip-\lastskip\fi + \nobreak\vbox{\noindent\kern\@totalleftmargin + {\color{spx@notice@bordercolor}% + \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax] + {\linewidth}{\spx@notice@border}}\hss}\allowbreak + }% end of sphinxlightbox environment definition +% may be renewenvironment'd by user for complete customization +\newenvironment{sphinxnote}[1] + {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} +\newenvironment{sphinxhint}[1] + {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} +\newenvironment{sphinximportant}[1] + {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} +\newenvironment{sphinxtip}[1] + {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} +% or just use the package options +% these are needed for common handling by notice environment of lightbox +% and heavybox but they are currently not used by lightbox environment +% and there is consequently no corresponding package option +\definecolor{sphinxnoteBgColor}{rgb}{1,1,1} +\definecolor{sphinxhintBgColor}{rgb}{1,1,1} +\definecolor{sphinimportantBgColor}{rgb}{1,1,1} +\definecolor{sphinxtipBgColor}{rgb}{1,1,1} + +% Others get more distinction % Code adapted from framed.sty's "snugshade" environment. % Nesting works (inner frames do not allow page breaks). -\newcommand{\py@heavybox}{\par - \setlength{\FrameRule}{\p@}% 1pt +\newenvironment{sphinxheavybox}{\par + \setlength{\FrameRule}{\spx@notice@border}% \setlength{\FrameSep}{\dimexpr.6\baselineskip-\FrameRule\relax} % configure framed.sty's parameters to obtain same vertical spacing % as for "light" boxes. We need for this to manually insert parskip glue and @@ -564,8 +723,10 @@ \vspace{\FrameHeightAdjust} % copied/adapted from framed.sty's snugshade \def\FrameCommand##1{\hskip\@totalleftmargin - \fboxsep\FrameSep \fboxrule\FrameRule\fbox{##1}% + \fboxsep\FrameSep \fboxrule\FrameRule + \fcolorbox{spx@notice@bordercolor}{spx@notice@bgcolor}{##1}% \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}% + \savenotes % use a minipage if we are already inside a framed environment \ifspx@inframed \noindent\begin{minipage}{\linewidth} @@ -581,67 +742,53 @@ \advance\hsize-\width \@totalleftmargin\z@ \linewidth\hsize % minipage initialization copied from LaTeX source code. \@pboxswfalse - % for footnotes - \def\@mpfn{mpfootnote}\def\thempfn{\thempfootnote}\c@mpfootnote\z@ - \let\@footnotetext\@mpfootnotetext \let\@listdepth\@mplistdepth \@mplistdepth\z@ \@minipagerestore \@setminipage }% } -\newcommand{\py@endheavybox}{% + {% \par\unskip - % handles footnotes - \ifvoid\@mpfootins\else - \vskip\skip\@mpfootins\normalcolor\footnoterule\unvbox\@mpfootins - \fi \@minipagefalse \endMakeFramed \ifspx@inframed\end{minipage}\fi + % set footnotes at bottom of page + \spewnotes % arrange for similar spacing below frame as for "light" boxes. \vskip .4\baselineskip - } - -\newcommand{\py@lightbox}{% - \par\allowbreak - \noindent\rule{\linewidth}{0.5pt}\par\nobreak - {\parskip\z@skip\noindent}% - } -\newcommand{\py@endlightbox}{% - \par - % counteract previous possible negative skip (French lists!): - % (we can't cancel that any earlier \vskip introduced a potential pagebreak) - \ifdim\lastskip<\z@\vskip-\lastskip\fi - \nobreak\vbox{\noindent\kern\@totalleftmargin - \rule[.4\baselineskip]{\linewidth}{0.5pt}\hss}\allowbreak - } - -% Some are quite plain: -\newcommand{\py@noticestart@note}{\py@lightbox} -\newcommand{\py@noticeend@note}{\py@endlightbox} -\newcommand{\py@noticestart@hint}{\py@lightbox} -\newcommand{\py@noticeend@hint}{\py@endlightbox} -\newcommand{\py@noticestart@important}{\py@lightbox} -\newcommand{\py@noticeend@important}{\py@endlightbox} -\newcommand{\py@noticestart@tip}{\py@lightbox} -\newcommand{\py@noticeend@tip}{\py@endlightbox} - -% Others gets more visible distinction: -\newcommand{\py@noticestart@warning}{\py@heavybox} -\newcommand{\py@noticeend@warning}{\py@endheavybox} -\newcommand{\py@noticestart@caution}{\py@heavybox} -\newcommand{\py@noticeend@caution}{\py@endheavybox} -\newcommand{\py@noticestart@attention}{\py@heavybox} -\newcommand{\py@noticeend@attention}{\py@endheavybox} -\newcommand{\py@noticestart@danger}{\py@heavybox} -\newcommand{\py@noticeend@danger}{\py@endheavybox} -\newcommand{\py@noticestart@error}{\py@heavybox} -\newcommand{\py@noticeend@error}{\py@endheavybox} - -\newenvironment{notice}[2]{ - \def\py@noticetype{#1} - \csname py@noticestart@#1\endcsname - \sphinxstrong{#2} % <- legacy code creates a space after {#2} -}{\csname py@noticeend@\py@noticetype\endcsname} + }% end of sphinxheavybox environment definition +% may be renewenvironment'd by user for complete customization +\newenvironment{sphinxwarning}[1] + {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} +\newenvironment{sphinxcaution}[1] + {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} +\newenvironment{sphinxattention}[1] + {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} +\newenvironment{sphinxdanger}[1] + {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} +\newenvironment{sphinxerror}[1] + {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}} +% or just use package options + +% the \colorlet of xcolor (if at all loaded) is overkill for our use case +\newcommand{\sphinxcolorlet}[2] + {\expandafter\let\csname\@backslashchar color@#1\expandafter\endcsname + \csname\@backslashchar color@#2\endcsname } + +% the main dispatch for all types of notices +\newenvironment{sphinxadmonition}{\begin{notice}}{\end{notice}} +% use of ``notice'' is for backwards compatibility and will be removed in +% future release; sphinxadmonition environment will be defined directly. +\newenvironment{notice}[2]{% #1=type, #2=heading + % can't use #1 directly in definition of end part + \def\spx@noticetype {#1}% + % set parameters of heavybox/lightbox + \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}% + \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}% + \spx@notice@border \dimexpr\csname spx@opt@#1border\endcsname\relax + % start specific environment, passing the heading as argument + \begin{sphinx#1}{#2}} + % in end part, need to go around a LaTeX's "feature" + {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp} % Allow the release number to be specified independently of the % \date{}. This allows the date to reflect the document's date and @@ -670,28 +817,33 @@ % This sets up the fancy chapter headings that make the documents look % at least a little better than the usual LaTeX output. % -\spx@ifundefined{ChTitleVar}{}{ - \ChNameVar{\raggedleft\normalsize\py@HeaderFamily} - \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily} - \ChTitleVar{\raggedleft \textrm{\Huge\py@HeaderFamily}} - % This creates chapter heads without the leading \vspace*{}: +\@ifpackagewith{fncychap}{Bjarne}{ + \ChNameVar {\raggedleft\normalsize \py@HeaderFamily} + \ChNumVar {\raggedleft\Large \py@HeaderFamily} + \ChTitleVar{\raggedleft\Large \py@HeaderFamily} + % This creates (numbered) chapter heads without the leading \vspace*{}: \def\@makechapterhead#1{% {\parindent \z@ \raggedright \normalfont \ifnum \c@secnumdepth >\m@ne - \DOCH + \if@mainmatter + \DOCH + \fi \fi \interlinepenalty\@M - \DOTI{#1} - } - } -} + \if@mainmatter + \DOTI{#1}% + \else% + \DOTIS{#1}% + \fi + }} +}{}% <-- "false" clause of \@ifpackagewith % Redefine description environment so that it is usable inside fulllineitems. % \renewcommand{\description}{% - \list{}{\labelwidth\z@% - \itemindent-\leftmargin% - \labelsep5pt% + \list{}{\labelwidth\z@ + \itemindent-\leftmargin + \labelsep5pt\relax \let\makelabel=\descriptionlabel}} % Definition lists; requested by AMK for HOWTO documents. Probably useful @@ -699,7 +851,7 @@ % \newenvironment{definitions}{% \begin{description}% - \def\term##1{\item[##1]\mbox{}\\*[0mm]} + \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}% }{% \end{description}% } @@ -707,7 +859,6 @@ % Tell TeX about pathological hyphenation cases: \hyphenation{Base-HTTP-Re-quest-Hand-ler} - % The following is stuff copied from docutils' latex writer. % \newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated @@ -728,27 +879,31 @@ {\setlength{\partopsep}{\parskip} \addtolength{\partopsep}{\baselineskip} \topsep0pt\itemsep0.15\baselineskip\parsep0pt - \leftmargin#1} + \leftmargin#1\relax} \raggedright} {\end{list}} -% Re-define \includegraphics to resize images larger than the line width -% if the size is not specified. +% Redefine \includegraphics to resize images larger than the line width, +% except if height or width option present. +% +% If scale is present, rescale before fitting to line width. (since 1.5) +% % Warning: future version of Sphinx will not modify original \includegraphics, -% Below custom code will be direct definition of \sphinxincludegraphics, with -% \py@Oldincludegraphics replaced by direct use of original \includegraphics. +% below code will be definition only of \sphinxincludegraphics. \let\py@Oldincludegraphics\includegraphics \newbox\spx@image@box -\renewcommand*{\includegraphics}[2][\@empty]{% - \ifx\@empty #1% attention, #1 could be bb.., bad if first after \ifx - \setbox\spx@image@box=\hbox{\py@Oldincludegraphics{#2}}% +\renewcommand*{\includegraphics}[2][]{% + \in@{height}{#1}\ifin@\else\in@{width}{#1}\fi + \ifin@ % height or width present + \py@Oldincludegraphics[#1]{#2}% + \else % no height nor width (but #1 may be "scale=...") + \setbox\spx@image@box\hbox{\py@Oldincludegraphics[#1,draft]{#2}}% \ifdim \wd\spx@image@box>\linewidth - \py@Oldincludegraphics[width=\linewidth]{#2}% + \setbox\spx@image@box\box\voidb@x % clear memory + \py@Oldincludegraphics[#1,width=\linewidth]{#2}% \else - \leavevmode\box\spx@image@box + \py@Oldincludegraphics[#1]{#2}% \fi - \else - \py@Oldincludegraphics[#1]{#2}% \fi } % Writer will put \sphinxincludegraphics in LaTeX source, and with this, @@ -774,32 +929,26 @@ \fi \fi -% Include hyperref last. -\RequirePackage[colorlinks,breaklinks, - linkcolor=InnerLinkColor,filecolor=OuterLinkColor, - menucolor=OuterLinkColor,urlcolor=OuterLinkColor, - citecolor=InnerLinkColor]{hyperref} -% Fix anchor placement for figures with captions. -% (Note: we don't use a package option here; instead, we give an explicit -% \capstart for figures that actually have a caption.) -\RequirePackage{hypcap} - -% Set up styles of URL: it should be placed after hyperref -\urlstyle{same} +% These options can be overriden inside 'hyperref' key +% or by later use of \hypersetup. +\PassOptionsToPackage{colorlinks,breaklinks,% + linkcolor=InnerLinkColor,filecolor=OuterLinkColor,% + menucolor=OuterLinkColor,urlcolor=OuterLinkColor,% + citecolor=InnerLinkColor}{hyperref} % From docutils.writers.latex2e % inline markup (custom roles) % \DUrole{#1}{#2} tries \DUrole#1{#2} \providecommand*{\DUrole}[2]{% - \ifcsname DUrole#1\endcsname% + \ifcsname DUrole#1\endcsname \csname DUrole#1\endcsname{#2}% \else% backwards compatibility: try \docutilsrole#1{#2} - \ifcsname docutilsrole#1\endcsname% + \ifcsname docutilsrole#1\endcsname \csname docutilsrole#1\endcsname{#2}% - \else% + \else #2% - \fi% - \fi% + \fi + \fi } \providecommand*{\DUprovidelength}[2]{% @@ -820,27 +969,11 @@ {\endlist} \fi -% From footmisc.sty: allows footnotes in titles -\let\FN@sf@@footnote\footnote -\def\footnote{\ifx\protect\@typeset@protect - \expandafter\FN@sf@@footnote - \else - \expandafter\FN@sf@gobble@opt - \fi -} -\edef\FN@sf@gobble@opt{\noexpand\protect - \expandafter\noexpand\csname FN@sf@gobble@opt \endcsname} -\expandafter\def\csname FN@sf@gobble@opt \endcsname{% - \@ifnextchar[%] - \FN@sf@gobble@twobracket - \@gobble -} -\def\FN@sf@gobble@twobracket[#1]#2{} - % adjust the margins for footer, % this works with the jsclasses only (Japanese standard document classes) +% FIXME: rather, pass options to "geometry". \ifx\@jsc@uplatextrue\undefined\else - \hypersetup{setpagesize=false} + \PassOptionsToPackage{setpagesize=false}{hyperref} \setlength\footskip{2\baselineskip} \addtolength{\textheight}{-2\baselineskip} \fi @@ -848,16 +981,15 @@ % fix the double index and bibliography on the table of contents % in jsclasses (Japanese standard document classes) \ifx\@jsc@uplatextrue\undefined\else - \renewcommand{\theindex}{ - \cleardoublepage - \phantomsection - \py@OldTheindex - } - \renewcommand{\thebibliography}[1]{ - \cleardoublepage - \phantomsection - \py@OldThebibliography{1} - } + \renewenvironment{sphinxtheindex} + {\cleardoublepage\phantomsection + \begin{theindex}} + {\end{theindex}} + + \renewenvironment{sphinxthebibliography}[1] + {\cleardoublepage\phantomsection + \begin{thebibliography}{1}} + {\end{thebibliography}} \fi % disable \@chappos in Appendix in pTeX @@ -869,13 +1001,25 @@ } \fi -% Define literal-block environment -\RequirePackage{newfloat} -\DeclareFloatingEnvironment{literal-block} +% for captions of literal blocks +% with `\theH...` macros for hyperref +\newcounter{literalblock} \spx@ifundefined{c@chapter} - {\SetupFloatingEnvironment{literal-block}{within=section,placement=h}} - {\SetupFloatingEnvironment{literal-block}{within=chapter,placement=h}} -\SetupFloatingEnvironment{literal-block}{name=List} + {\@addtoreset{literalblock}{section} + \def\theliteralblock {\ifnum\c@section>\z@ \thesection.\fi\arabic{literalblock}} + \def\theHliteralblock {\theHsection.\arabic{literalblock}}} + {\@addtoreset{literalblock}{chapter} + \def\theliteralblock {\ifnum\c@chapter>\z@ \thechapter.\fi\arabic{literalblock}} + \def\theHliteralblock {\theHchapter.\arabic{literalblock}}} +% at start of caption title +\newcommand*{\fnum@literalblock}{\literalblockname\nobreakspace\theliteralblock} +% this will be overwritten in document preamble by Babel translation +\newcommand*{\literalblockname}{Listing } +% file extension needed for \caption's good functioning, the file is created +% only if a \listof{literalblock}{foo} command is encountered, which is +% analogous to \listoffigures, but for the code listings (foo = chosen title.) +\newcommand*{\ext@literalblock}{lol} + % control caption around literal-block \RequirePackage{capt-of} \RequirePackage{needspace} @@ -896,22 +1040,117 @@ \spx@originalcaption } % by default, also define macros with the no-prefix names -\ifsphinxKeepOldNames +\ifspx@opt@dontkeepoldnames\else \typeout{** (sphinx) defining (legacy) text style macros without \string\sphinx\space prefix} - \typeout{** if clashes with packages, set latex_keep_old_macro_names=False in conf.py} - \@for\@tempa:=strong,bfcode,email,tablecontinued,titleref,% + \typeout{** if clashes with packages, set latex_keep_old_macro_names=False + in conf.py} + \@for\@tempa:=code,strong,bfcode,email,tablecontinued,titleref,% menuselection,accelerator,crossref,termref,optional\do {% first, check if command with no prefix already exists \expandafter\newcommand\csname\@tempa\endcsname{}% - % if no error give it the meaning defined so far with \sphinx prefix + % give it the meaning defined so far with \sphinx prefix \expandafter\let\csname\@tempa\expandafter\endcsname \csname sphinx\@tempa\endcsname % redefine the \sphinx prefixed macro to expand to non-prefixed one \expandafter\def\csname sphinx\@tempa\expandafter\endcsname \expandafter{\csname\@tempa\endcsname}% -} - % robustified case needs special treatment - \newcommand\code{}\let\code\relax - \DeclareRobustCommand{\code}[1]{{\@noligs\scantokens{\texttt{#1}\relax}}} - \def\sphinxcode{\code}% +}% \fi + +% additional customizable styling +% FIXME: convert this to package options ? +\protected\def\sphinxstyleindexentry {\texttt} +\long\protected\def\sphinxstyleindexextra #1{ \emph{(#1)}} +\protected\def\sphinxstyleindexpageref {, \pageref} +\long\protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip} +\let\sphinxstylesidebartitle\sphinxstyletopictitle +\protected\def\sphinxstyleothertitle {\textbf} +\long\protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip} +\protected\def\sphinxstylethead {\textsf} +\protected\def\sphinxstyleemphasis {\emph} +\long\protected\def\sphinxstyleliteralemphasis#1{\emph{\sphinxcode{#1}}} +\protected\def\sphinxstylestrong {\textbf} +\protected\def\sphinxstyleliteralstrong {\sphinxbfcode} +\protected\def\sphinxstyleabbreviation {\textsc} +\protected\def\sphinxstyleliteralintitle {\sphinxcode} + +% stylesheet for highlighting with pygments +\RequirePackage{sphinxhighlight} + +% make commands known to non-Sphinx document classes +\providecommand*{\sphinxtableofcontents}{\tableofcontents} +\providecommand*{\sphinxthebibliography}{\thebibliography} +\providecommand*{\sphinxtheindex}{\theindex} + +% remove LaTeX's cap on nesting depth if 'maxlistdepth' key used. +% This is a hack, which works with the standard classes: it assumes \@toodeep +% is always used in "true" branches: "\if ... \@toodeep \else .. \fi." + +% will force use the "false" branch (if there is one) +\def\spx@toodeep@hack{\fi\iffalse} + +% do nothing if 'maxlistdepth' key not used or if package enumitem loaded. +\ifnum\spx@opt@maxlistdepth=\z@\expandafter\@gobbletwo\fi +\AtBeginDocument{% +\@ifpackageloaded{enumitem}{\remove@to@nnil}{}% + \let\spx@toodeepORI\@toodeep + \def\@toodeep{% + \ifnum\@listdepth<\spx@opt@maxlistdepth\relax + \expandafter\spx@toodeep@hack + \else + \expandafter\spx@toodeepORI + \fi}% +% define all missing \@list... macros + \count@\@ne + \loop + \spx@ifundefined{@list\romannumeral\the\count@} + {\iffalse}{\iftrue\advance\count@\@ne}% + \repeat + \loop + \ifnum\count@>\spx@opt@maxlistdepth\relax\else + \expandafter\let + \csname @list\romannumeral\the\count@\expandafter\endcsname + \csname @list\romannumeral\the\numexpr\count@-\@ne\endcsname + % higher \leftmargin... needed to fix issue with babel-french (v2.6--...) + \spx@ifundefined{leftmargin\romannumeral\the\count@} + {\expandafter\let + \csname leftmargin\romannumeral\the\count@\expandafter\endcsname + \csname leftmargin\romannumeral\the\numexpr\count@-\@ne\endcsname}{}% + \advance\count@\@ne + \repeat +% define all missing enum... counters and \labelenum... macros and \p@enum.. + \count@\@ne + \loop + \spx@ifundefined{c@enum\romannumeral\the\count@} + {\iffalse}{\iftrue\advance\count@\@ne}% + \repeat + \loop + \ifnum\count@>\spx@opt@maxlistdepth\relax\else + \newcounter{enum\romannumeral\the\count@}% + \expandafter\def + \csname labelenum\romannumeral\the\count@\expandafter\endcsname + \expandafter + {\csname theenum\romannumeral\the\numexpr\count@\endcsname.}% + \expandafter\def + \csname p@enum\romannumeral\the\count@\expandafter\endcsname + \expandafter + {\csname p@enum\romannumeral\the\numexpr\count@-\@ne\expandafter + \endcsname\csname theenum\romannumeral\the\numexpr\count@-\@ne\endcsname.}% + \advance\count@\@ne + \repeat +% define all missing labelitem... macros + \count@\@ne + \loop + \spx@ifundefined{labelitem\romannumeral\the\count@} + {\iffalse}{\iftrue\advance\count@\@ne}% + \repeat + \loop + \ifnum\count@>\spx@opt@maxlistdepth\relax\else + \expandafter\let + \csname labelitem\romannumeral\the\count@\expandafter\endcsname + \csname labelitem\romannumeral\the\numexpr\count@-\@ne\endcsname + \advance\count@\@ne + \repeat + \PackageInfo{sphinx}{maximal list depth extended to \spx@opt@maxlistdepth}% +\@gobble\@nnil +} |