path: root/sphinx/texinputs/sphinxlatexobjects.sty

%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexobjects.sty}[2021/12/05 documentation environments]

% Provides support for this output mark-up from Sphinx latex writer:
%
% - environments
%
%   - fulllineitems
%   - productionlist
%   - optionlist
%   - DUlineblock (also "lineblock")
%
% - macros
%
%   - \DUrole
%   - various legacy support macros related to author and release
%     data of documented objects and modules.

% \moduleauthor{name}{email}
\newcommand{\moduleauthor}[2]{}

% \sectionauthor{name}{email}
\newcommand{\sectionauthor}[2]{}

% Allow the release number to be specified independently of the
% \date{}.  This allows the date to reflect the document's date and
% release to specify the release that is documented.
%
\newcommand{\py@release}{\releasename\space\version}
\newcommand{\version}{}% part of \py@release, used by title page and headers
% \releaseinfo is used on titlepage (sphinxmanual.cls, sphinxhowto.cls)
\newcommand{\releaseinfo}{}
\newcommand{\setreleaseinfo}[1]{\renewcommand{\releaseinfo}{#1}}
% this is inserted via template and #1=release config variable
\newcommand{\release}[1]{\renewcommand{\version}{#1}}
% this is defined by template to 'releasename' latex_elements key
\newcommand{\releasename}{}
% Fix issue in case release and releasename deliberately left blank
\newcommand{\sphinxheadercomma}{, }% used in fancyhdr header definition
\newcommand{\sphinxifemptyorblank}[1]{%
% test after one expansion of macro #1 if contents is empty or spaces
     \if&\expandafter\@firstofone\detokenize\expandafter{#1}&%
     \expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}%
\AtBeginDocument {%
   \sphinxifemptyorblank{\releasename}
     {\sphinxifemptyorblank{\version}{\let\sphinxheadercomma\empty}{}}
     {}%
}%

% Allow specification of the author's address separately from the
% author's name.  This can be used to format them differently, which
% is a good thing.
%
\newcommand{\py@authoraddress}{}
\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}

% {fulllineitems} is the main environment for object descriptions.
%
% With 4.0.0 \pysigline (and \pysiglinewithargsret), used in a fulllineitems
% environment the #1 will already be of the width which is computed here, i.e.
% the available width on line, so the \makebox becomes a bit superfluous
\newcommand{\py@itemnewline}[1]{% macro used as \makelabel in fulllineitems
% Memo: this presupposes \itemindent is 0pt
  \kern\labelsep  % because \@labels core latex box does \hskip-\labelsep
  \makebox[\dimexpr\linewidth+\labelwidth\relax][l]{#1}%
  \kern-\labelsep % because at end of \@labels box there is \hskip\labelsep
}

\newenvironment{fulllineitems}{%
  \begin{list}{}{\labelwidth \leftmargin
                 \rightmargin \z@ \topsep -\parskip \partopsep \parskip
                 \itemsep -\parsep
                 \let\makelabel=\py@itemnewline}%
}{\end{list}}

% Signatures, possibly multi-line
%
\newlength{\py@argswidth}
\newcommand{\py@sigparams}[2]{%
  % The \py@argswidth has been computed in \pysiglinewithargsret to make this
  % occupy full available width on line.
  \parbox[t]{\py@argswidth}{\raggedright #1\sphinxcode{)}#2\strut}%
  % final strut is to help get correct vertical separation in case of multi-line
  % box with the item contents. 
}
\newcommand{\pysigline}[1]{%
% the \py@argswidth is available we use it despite its name (no "args" here)
% the \relax\relax is because \py@argswidth is a "skip" variable and the first
% \relax only ends its "dimen" part
  \py@argswidth=\dimexpr\linewidth+\labelwidth\relax\relax
  \item[{\parbox[t]{\py@argswidth}{\raggedright #1\strut}}]
  \futurelet\sphinx@token\pysigline@preparevspace@i
}
\newcommand{\pysiglinewithargsret}[3]{%
  \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
  \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}\strut}]
  \futurelet\sphinx@token\pysigline@preparevspace@i
}
\def\pysigline@preparevspace@i{%
  \ifx\sphinx@token\@sptoken
   \expandafter\pysigline@preparevspace@again
   \else\expandafter\pysigline@preparevspace@ii
  \fi
}
\@firstofone{\def\pysigline@preparevspace@again} {\futurelet\sphinx@token\pysigline@preparevspace@i}
\long\def\pysigline@preparevspace@ii#1{%
  \ifx\sphinx@token\bgroup\expandafter\@firstoftwo
  \else
    \ifx\sphinx@token\phantomsection
    \else
% this strange incantation is because at its root LaTeX in fact did not
% imagine a multi-line label, it is always wrapped in a horizontal box at core
% LaTeX level and we have to find tricks to get correct interline distances.
% It interacts badly with a follow-up \phantomsection hence the test above
    \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox
    \fi
    \expandafter\@secondoftwo
  \fi
  {{#1}}{#1}%
}
\newcommand{\pysigstartmultiline}{%
 \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}%
 \edef\pysigstopmultiline
     {\noexpand\leavevmode\parskip\the\parskip\relax\itemsep\the\itemsep\relax}%
 \parskip\z@skip\itemsep\z@skip
}

% Production lists
%
\newenvironment{productionlist}{%
%  \def\sphinxoptional##1{{\Large[}##1{\Large]}}
  \def\production##1##2{\\\sphinxcode{\sphinxupquote{##1}}&::=&\sphinxcode{\sphinxupquote{##2}}}%
  \def\productioncont##1{\\& &\sphinxcode{\sphinxupquote{##1}}}%
  \parindent=2em
  \indent
  \setlength{\LTpre}{0pt}%
  \setlength{\LTpost}{0pt}%
  \begin{longtable}[l]{lcl}
}{%
  \end{longtable}
}

% Definition lists; requested by AMK for HOWTO documents.  Probably useful
% elsewhere as well, so keep in in the general style support.
%
\newenvironment{definitions}{%
  \begin{description}%
  \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}%
}{%
  \end{description}%
}

%% FROM DOCTUTILS LATEX WRITER
%
% The following is stuff copied from docutils' latex writer.
%
\newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated
\newenvironment{optionlist}[1]
{\begin{list}{}
  {\setlength{\labelwidth}{#1}
   \setlength{\rightmargin}{1cm}
   \setlength{\leftmargin}{\rightmargin}
   \addtolength{\leftmargin}{\labelwidth}
   \addtolength{\leftmargin}{\labelsep}
   \renewcommand{\makelabel}{\optionlistlabel}}
}{\end{list}}

\newlength{\lineblockindentation}
\setlength{\lineblockindentation}{2.5em}
\newenvironment{lineblock}[1]
{\begin{list}{}
  {\setlength{\partopsep}{\parskip}
   \addtolength{\partopsep}{\baselineskip}
   \topsep0pt\itemsep0.15\baselineskip\parsep0pt
   \leftmargin#1\relax}
 \raggedright}
{\end{list}}

% From docutils.writers.latex2e
% inline markup (custom roles)
% \DUrole{#1}{#2} tries \DUrole#1{#2}
\providecommand*{\DUrole}[2]{%
  \ifcsname DUrole\detokenize{#1}\endcsname
    \csname DUrole\detokenize{#1}\endcsname{#2}%
  \else% backwards compatibility: try \docutilsrole#1{#2}
    \ifcsname docutilsrole\detokenize{#1}\endcsname
      \csname docutilsrole\detokenize{#1}\endcsname{#2}%
    \else
      #2%
    \fi
  \fi
}

\providecommand*{\DUprovidelength}[2]{%
  \ifdefined#1\else\newlength{#1}\setlength{#1}{#2}\fi
}

\DUprovidelength{\DUlineblockindent}{2.5em}
\ifdefined\DUlineblock\else
  \newenvironment{DUlineblock}[1]{%
    \list{}{\setlength{\partopsep}{\parskip}
            \addtolength{\partopsep}{\baselineskip}
            \setlength{\topsep}{0pt}
            \setlength{\itemsep}{0.15\baselineskip}
            \setlength{\parsep}{0pt}
            \setlength{\leftmargin}{#1}}
    \raggedright
  }
  {\endlist}
\fi

\endinput