path: root/sphinx/texinputs/sphinxlatexobjects.sty

%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexobjects.sty}[2023/07/23 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
%
% For legacy reasons Sphinx uses LaTeX \list and \item's for signatures
% This is delicate:
% - the actual item label is not typeset immediately by \item but later as part
% of the \everypar which will be triggered by either next paragraph or a manual
% \leavevmode, or if nothing in-between by the next \item,
% - \begingroup <set-up>\item[foo] <setup>\endgroup leads to errors,
% - vertical space depends on \parskip and \itemsep values in somewhat
% subtle manners.
%
% Since the 2022/01/13 version things are simpler as \parskip is simply set
% to zero during execution of \pysigline/\pysiglinewithargsret
%
% Parameter for separation via \itemsep of multiple signatures with common desc
\newlength\sphinxsignaturesep
\setlength\sphinxsignaturesep{\smallskipamount}
% latex.py outputs mark-up like this:
% \pysigstartsignatures <signatures> \pysigstopsignatures <actual desc>
\newcommand{\pysigstartsignatures}{%
   % store current \parskip and \itemsep
   \edef\pysig@restore@itemsep@and@parskip{%
       \itemsep\the\itemsep\relax
       \parskip\the\parskip\relax
   }%
   % set them to control the spacing between signatures sharing common desc
   \parskip\z@skip
   \itemsep\sphinxsignaturesep
}
\newcommand{\pysigstopsignatures}{%
% 1) encourage a pagebreak in an attempt to try to avoid last
% signature ending up separated from description (due to voodoo next)
\penalty-100
% 2) some voodoo to separate last signature from description in a manner
% robust with respect to the latter being itself a LaTeX list object
\leavevmode\par\kern-\baselineskip\item[\strut]
%
   \leavevmode
   % it is important \leavevmode was issued before the \parskip reset, and
   % it is also needed for the case of an object desc itself a LaTeX \list
   % now restore \itemsep and \parskip
   \pysig@restore@itemsep@and@parskip
}
% Each signature is rendered as NAME<SPACE>[TPLIST]<SPACE>(ARGLIST) where the
% size of <SPACE> is parametrized by \sphinxsignaturelistskip (0pt by default).
\newlength\sphinxsignaturelistskip
\setlength\sphinxsignaturelistskip{0pt}
\newcommand{\pysigtypelistopen}{\hskip\sphinxsignaturelistskip\sphinxcode{[}}
\newcommand{\pysigtypelistclose}{\sphinxcode{]}}
\newcommand{\pysigarglistopen}{\hskip\sphinxsignaturelistskip\sphinxcode{(}}
\newcommand{\pysigarglistclose}{\sphinxcode{)}}
%
% Use a \parbox to accommodate long argument list in signatures
% LaTeX did not imagine that an \item label could need multi-line rendering
\newlength{\py@argswidth}
\newcommand{\py@sigparams}[2]{%
  % The \py@argswidth has been computed in \pysiglinewithargsret to make the
  % argument list use full available width
  \parbox[t]{\py@argswidth}{\raggedright #1\pysigarglistclose#2\strut}%
  % final strut is to help get correct vertical separation
}
\newcommand{\py@sigparamswithtypelist}[3]{%
  % similar to \py@sigparams but with different delimiters and an additional
  % type parameters list given as #1, the argument list as #2 and the return
  % annotation as #3
  \parbox[t]{\py@argswidth}{%
    \raggedright #1\pysigtypelistclose%
    \pysigarglistopen#2\pysigarglistclose%
    #3\strut}%
}

\newcommand{\pysigline}[1]{%
  % as \py@argswidth is available, we use it but no "args" here
  % the \relax\relax is because \py@argswidth is a "skip" variable
  % this will make the label occupy the full available linewidth
  \py@argswidth=\dimexpr\linewidth+\labelwidth\relax\relax
  \item[{\parbox[t]{\py@argswidth}{\raggedright #1\strut}}]
  \pysigadjustitemsep
}
\newcommand{\pysiglinewithargsret}[3]{%
  % as #1 may contain a footnote using \label we need to make \label
  % a no-op here to avoid LaTeX complaining about duplicates
\let\spx@label\label\let\label\@gobble
  \settowidth{\py@argswidth}{#1\pysigarglistopen}%
\let\label\spx@label
  \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
  \item[{#1\pysigarglistopen\py@sigparams{#2}{#3}\strut}]
  \pysigadjustitemsep
}
\newcommand{\pysiglinewithargsretwithtypelist}[4]{
% #1 = name, #2 = typelist, #3 = arglist, #4 = retann
\let\spx@label\label\let\label\@gobble
  \settowidth{\py@argswidth}{#1\pysigtypelistopen}%
\let\label\spx@label
  \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
  \item[{#1\pysigtypelistopen\py@sigparamswithtypelist{#2}{#3}{#4}\strut}]
  \pysigadjustitemsep
}

\def\sphinxoptionalextraspace{0.5mm}
\newcommand{\pysigwithonelineperarg}[3]{%
  % render each argument on its own line
  \item[#1\pysigarglistopen\strut]
  \leavevmode\par\nopagebreak
  % this relies on \pysigstartsignatures having set \parskip to zero
  \begingroup
     \let\sphinxparamcomma\sphinxparamcommaoneperline
     \def\sphinxoptionalhook{\ifvmode\else\kern\sphinxoptionalextraspace\relax\fi}%
     % The very first \sphinxparam should not emit a \par hence a complication
     % with a group and global definition here as it may occur in a \sphinxoptional
     \global\let\spx@sphinxparam\sphinxparam
     \gdef\sphinxparam{\gdef\sphinxparam{\par\spx@sphinxparam}\spx@sphinxparam}%
  #2\par
  \endgroup
  \global\let\sphinxparam\spx@sphinxparam
  % fulllineitems sets \labelwidth to be like \leftmargin
  \nopagebreak\noindent\kern-\labelwidth\pysigarglistclose{#3}
  \pysigadjustitemsep
}
\newcommand{\pysigwithonelineperargwithonelinepertparg}[4]{
  % #1 = name, #2 = typelist, #3 = arglist, #4 = retann
  % render each type parameter and argument on its own line
  \item[#1\pysigtypelistopen\strut]
  \leavevmode\par\nopagebreak
  \begingroup
     \let\sphinxparamcomma\sphinxparamcommaoneperline
     % \sphinxtypeparam is treated similarly to \sphinxparam but since
     % \sphinxoptional is not accepted in a type parameters list, we do
     % not need the hook or the global definition
     \let\spx@sphinxtypeparam\sphinxtypeparam
     \def\sphinxtypeparam{\def\sphinxtypeparam{\par\spx@sphinxtypeparam}\spx@sphinxtypeparam}%
  #2\par
  \endgroup
  \nopagebreak\noindent\kern-\labelwidth\pysigtypelistclose%
  % render the rest of the signature like in \pysigwithonelineperarg
  \pysigarglistopen\strut\par\nopagebreak
  \begingroup
     \let\sphinxparamcomma\sphinxparamcommaoneperline
     \def\sphinxoptionalhook{\ifvmode\else\kern\sphinxoptionalextraspace\relax\fi}%
     \global\let\spx@sphinxparam\sphinxparam
     \gdef\sphinxparam{\gdef\sphinxparam{\par\spx@sphinxparam}\spx@sphinxparam}%
  #3\par
  \endgroup
  \global\let\sphinxparam\spx@sphinxparam
  \nopagebreak\noindent\kern-\labelwidth\pysigarglistclose{#4}
  \pysigadjustitemsep
}
\newcommand{\pysiglinewithargsretwithonelinepertparg}[4]{
  % #1 = name, #2 = typelist, #3 = arglist, #4 = retann
  % render each type parameter on its own line but the arguments list inline
  \item[#1\pysigtypelistopen\strut]
  \leavevmode\par\nopagebreak
  \begingroup
     \let\sphinxparamcomma\sphinxparamcommaoneperline
     % \sphinxtypeparam is treated similarly to \sphinxparam but since
     % \sphinxoptional is not accepted in a type parameters list, we do
     % not need the hook or the global definition
     \let\spx@sphinxtypeparam\sphinxtypeparam
     \def\sphinxtypeparam{\def\sphinxtypeparam{\par\spx@sphinxtypeparam}\spx@sphinxtypeparam}%
  #2\par
  \endgroup
  \nopagebreak\noindent\kern-\labelwidth\pysigtypelistclose%
  % render the arguments list on one line
  \pysigarglistopen#3\pysigarglistclose#4\strut
  \pysigadjustitemsep
}
\newcommand{\pysigwithonelineperargwithtypelist}[4]{
  % #1 = name, #2 = typelist, #3 = arglist, #4 = retann
  % render the type parameters list on one line, but each argument is rendered on its own line
\let\spx@label\label\let\label\@gobble
  \settowidth{\py@argswidth}{#1\pysigtypelistopen}%
\let\label\spx@label
  \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
  \item[{#1\pysigtypelistopen\parbox[t]{\py@argswidth}{%
    \raggedright #2\pysigtypelistclose\pysigarglistopen\strut}\strut}]
  % render the rest of the signature like in \pysigwithonelineperarg
  \begingroup
     \let\sphinxparamcomma\sphinxparamcommaoneperline
     \def\sphinxoptionalhook{\ifvmode\else\kern\sphinxoptionalextraspace\relax\fi}%
     \global\let\spx@sphinxparam\sphinxparam
     \gdef\sphinxparam{\gdef\sphinxparam{\par\spx@sphinxparam}\spx@sphinxparam}%
  #3\par
  \endgroup
  \global\let\sphinxparam\spx@sphinxparam
  \nopagebreak\noindent\kern-\labelwidth\pysigarglistclose{#4}
  \pysigadjustitemsep
}
\newcommand{\pysigadjustitemsep}{%
  % adjust \itemsep to control the separation with the next signature
  % sharing common description
  \ifsphinxsigismultiline
  % inside a multiline signature, no extra vertical spacing
  % ("multiline" here does not refer to possibly long
  %  list of arguments, but to a cpp domain feature)
      \itemsep\z@skip
  \else
      \itemsep\sphinxsignaturesep
  \fi
}
\newif\ifsphinxsigismultiline
\newcommand{\pysigstartmultiline}{\sphinxsigismultilinetrue}%
\newcommand{\pysigstopmultiline}{\sphinxsigismultilinefalse\itemsep\sphinxsignaturesep}%

% 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