1%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
2%
3% change this info string if making any custom modification
4\ProvidesFile{sphinxlatexobjects.sty}[2021/01/27 documentation environments]
5
6% Provides support for this output mark-up from Sphinx latex writer:
7%
8% - environments
9%
10%   - fulllineitems
11%   - productionlist
12%   - optionlist
13%   - DUlineblock (also "lineblock")
14%
15% - macros
16%
17%   - \DUrole
18%   - various legacy support macros related to author and release
19%     data of documented objects and modules.
20
21% \moduleauthor{name}{email}
22\newcommand{\moduleauthor}[2]{}
23
24% \sectionauthor{name}{email}
25\newcommand{\sectionauthor}[2]{}
26
27% Allow the release number to be specified independently of the
28% \date{}.  This allows the date to reflect the document's date and
29% release to specify the release that is documented.
30%
31\newcommand{\py@release}{\releasename\space\version}
32\newcommand{\version}{}% part of \py@release, used by title page and headers
33% \releaseinfo is used on titlepage (sphinxmanual.cls, sphinxhowto.cls)
34\newcommand{\releaseinfo}{}
35\newcommand{\setreleaseinfo}[1]{\renewcommand{\releaseinfo}{#1}}
36% this is inserted via template and #1=release config variable
37\newcommand{\release}[1]{\renewcommand{\version}{#1}}
38% this is defined by template to 'releasename' latex_elements key
39\newcommand{\releasename}{}
40% Fix issue in case release and releasename deliberately left blank
41\newcommand{\sphinxheadercomma}{, }% used in fancyhdr header definition
42\newcommand{\sphinxifemptyorblank}[1]{%
43% test after one expansion of macro #1 if contents is empty or spaces
44     \if&\expandafter\@firstofone\detokenize\expandafter{#1}&%
45     \expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}%
46\AtBeginDocument {%
47   \sphinxifemptyorblank{\releasename}
48     {\sphinxifemptyorblank{\version}{\let\sphinxheadercomma\empty}{}}
49     {}%
50}%
51
52% Allow specification of the author's address separately from the
53% author's name.  This can be used to format them differently, which
54% is a good thing.
55%
56\newcommand{\py@authoraddress}{}
57\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
58
59% {fulllineitems} is the main environment for object descriptions.
60%
61% With 4.0.0 \pysigline (and \pysiglinewithargsret), used in a fulllineitems
62% environment the #1 will already be of the width which is computed here, i.e.
63% the available width on line, so the \makebox becomes a bit superfluous
64\newcommand{\py@itemnewline}[1]{% macro used as \makelabel in fulllineitems
65% Memo: this presupposes \itemindent is 0pt
66  \kern\labelsep  % because \@labels core latex box does \hskip-\labelsep
67  \makebox[\dimexpr\linewidth+\labelwidth\relax][l]{#1}%
68  \kern-\labelsep % because at end of \@labels box there is \hskip\labelsep
69}
70
71\newenvironment{fulllineitems}{%
72  \begin{list}{}{\labelwidth \leftmargin
73                 \rightmargin \z@ \topsep -\parskip \partopsep \parskip
74                 \itemsep -\parsep
75                 \let\makelabel=\py@itemnewline}%
76}{\end{list}}
77
78% Signatures, possibly multi-line
79%
80\newlength{\py@argswidth}
81\newcommand{\py@sigparams}[2]{%
82  % The \py@argswidth has been computed in \pysiglinewithargsret to make this
83  % occupy full available width on line.
84  \parbox[t]{\py@argswidth}{\raggedright #1\sphinxcode{)}#2\strut}%
85  % final strut is to help get correct vertical separation in case of multi-line
86  % box with the item contents.
87}
88\newcommand{\pysigline}[1]{%
89% the \py@argswidth is available we use it despite its name (no "args" here)
90% the \relax\relax is because \py@argswidth is a "skip" variable and the first
91% \relax only ends its "dimen" part
92  \py@argswidth=\dimexpr\linewidth+\labelwidth\relax\relax
93  \item[{\parbox[t]{\py@argswidth}{\raggedright #1\strut}}]
94% contrarily to \pysiglinewithargsret, we do not do this:
95%  \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox
96% which would give exact vertical spacing if item parbox is multi-line,
97% as it affects negatively more common situation of \pysigline
98% used twice or more in a row for labels sharing common description,
99% due to bad interaction with the \phantomsection in the mark-up
100}
101\newcommand{\pysiglinewithargsret}[3]{%
102  \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
103  \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
104  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]
105% this strange incantation is because at its root LaTeX in fact did not
106% imagine a multi-line label, it is always wrapped in a horizontal box at core
107% LaTeX level and we have to find tricks to get correct interline distances.
108  \leavevmode\par\nobreak\vskip-\parskip\prevdepth\dp\strutbox}
109\newcommand{\pysigstartmultiline}{%
110 \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}%
111 \edef\pysigstopmultiline
112     {\noexpand\leavevmode\parskip\the\parskip\relax\itemsep\the\itemsep\relax}%
113 \parskip\z@skip\itemsep\z@skip
114}
115
116% Production lists
117%
118\newenvironment{productionlist}{%
119%  \def\sphinxoptional##1{{\Large[}##1{\Large]}}
120  \def\production##1##2{\\\sphinxcode{\sphinxupquote{##1}}&::=&\sphinxcode{\sphinxupquote{##2}}}%
121  \def\productioncont##1{\\& &\sphinxcode{\sphinxupquote{##1}}}%
122  \parindent=2em
123  \indent
124  \setlength{\LTpre}{0pt}%
125  \setlength{\LTpost}{0pt}%
126  \begin{longtable}[l]{lcl}
127}{%
128  \end{longtable}
129}
130
131% Definition lists; requested by AMK for HOWTO documents.  Probably useful
132% elsewhere as well, so keep in in the general style support.
133%
134\newenvironment{definitions}{%
135  \begin{description}%
136  \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}%
137}{%
138  \end{description}%
139}
140
141%% FROM DOCTUTILS LATEX WRITER
142%
143% The following is stuff copied from docutils' latex writer.
144%
145\newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated
146\newenvironment{optionlist}[1]
147{\begin{list}{}
148  {\setlength{\labelwidth}{#1}
149   \setlength{\rightmargin}{1cm}
150   \setlength{\leftmargin}{\rightmargin}
151   \addtolength{\leftmargin}{\labelwidth}
152   \addtolength{\leftmargin}{\labelsep}
153   \renewcommand{\makelabel}{\optionlistlabel}}
154}{\end{list}}
155
156\newlength{\lineblockindentation}
157\setlength{\lineblockindentation}{2.5em}
158\newenvironment{lineblock}[1]
159{\begin{list}{}
160  {\setlength{\partopsep}{\parskip}
161   \addtolength{\partopsep}{\baselineskip}
162   \topsep0pt\itemsep0.15\baselineskip\parsep0pt
163   \leftmargin#1\relax}
164 \raggedright}
165{\end{list}}
166
167% From docutils.writers.latex2e
168% inline markup (custom roles)
169% \DUrole{#1}{#2} tries \DUrole#1{#2}
170\providecommand*{\DUrole}[2]{%
171  \ifcsname DUrole\detokenize{#1}\endcsname
172    \csname DUrole\detokenize{#1}\endcsname{#2}%
173  \else% backwards compatibility: try \docutilsrole#1{#2}
174    \ifcsname docutilsrole\detokenize{#1}\endcsname
175      \csname docutilsrole\detokenize{#1}\endcsname{#2}%
176    \else
177      #2%
178    \fi
179  \fi
180}
181
182\providecommand*{\DUprovidelength}[2]{%
183  \ifdefined#1\else\newlength{#1}\setlength{#1}{#2}\fi
184}
185
186\DUprovidelength{\DUlineblockindent}{2.5em}
187\ifdefined\DUlineblock\else
188  \newenvironment{DUlineblock}[1]{%
189    \list{}{\setlength{\partopsep}{\parskip}
190            \addtolength{\partopsep}{\baselineskip}
191            \setlength{\topsep}{0pt}
192            \setlength{\itemsep}{0.15\baselineskip}
193            \setlength{\parsep}{0pt}
194            \setlength{\leftmargin}{#1}}
195    \raggedright
196  }
197  {\endlist}
198\fi
199
200\endinput
201