1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
%% MODULE RELEASE DATA AND OBJECT DESCRIPTIONS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexobjects.sty}[2022/01/13 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
}
%
% Use a \parbox to accomodate 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\sphinxcode{)}#2\strut}%
  % final strut is to help get correct vertical separation
}
\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]{%
  \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
  \py@argswidth=\dimexpr\linewidth+\labelwidth-\py@argswidth\relax\relax
  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}\strut}]
  \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