PlasmaCalcs.tools.docs_tools.DocstringInfo

class PlasmaCalcs.tools.docs_tools.DocstringInfo(docstring, *, kind=None)

Bases: object

info about a docstring. Also, helpful methods for converting to sphinx format.
docstring: str
the original docstring. Stored at self.docstring, and never changed.
kind: None, ‘sphinx’, or ‘custom’
what kind of docstring this is.
None –> infer from docstring.
‘sphinx’ if any line matches the KNOWN_SPHINX_PATTERN, else ‘custom’.
(e.g. if there’s a :param…: line, then it’s ‘sphinx’.)
‘sphinx’ –> docstring assumed to already follow all sphinx standards.
‘custom’ –> docstring assumed to not follow sphinx standards. (See below)
“Custom” format is used throughout most of PlasmaCalcs. Details:
- first line is a description of the object. Never a param or other special line.
- subsequent lines might continue the description.
- line breaks are intended to be maintained when generating docs pages.
- some lines tell params but don’t specify :param:. Example:

word: description with any number of words

- after a param line, subsequent indented lines are a description of that param,
until indentation level reverts back to same level as param line. Example:
myparam1: description of myparam1
continues description of myparam1

also part of description of myparam1
no longer part of description (might be a different param, or something else).
- param “word” could instead be comma-separated words, but nothing fancier.
E.g. “x, y: value” is treated as params, but “x space: value” is not.
“Word” is defined to be a sequence of characters matching regex: w
Also, these can never be single-word params:
‘Example’, ‘Examples’, ‘Return’, ‘Returns’
- currently, no other fancy-formatting is recognized.
- (this might be updated eventually)
- some patterns will be replaced:
|x| –> \|x| # to avoid sphinx interpreting as “substitution”.
x –> `x` # to tell sphinx to interpret as “code”
If you don’t like all the details of “custom” format, you can just use sphinx format.
__init__(docstring, *, kind=None)

Methods

__init__(docstring, *[, kind])

from_obj(obj)

get_indent_n(line)

is_blank_line(line)

line_infos()

nonblank_line_here_or_next(i)

param_ilines()

to_sphinx()

to_sphinx_lines()

Attributes

KNOWN_SPHINX_PATTERN

PARAM_PATTERN

classmethod from_obj(obj)
return DocstringInfo(obj.__doc__)
static get_indent_n(line)
returns number of leading spaces in line.
static is_blank_line(line)
returns whether this line is blank.
line_infos()
return (i, linetype, indent_n, line_post_indent) for each line in docstring.
i is line index.
linetype is ‘text’, ‘empty’, ‘param’, or ‘pdesc’.
‘text’ –> misc text (not associated with a param)
‘empty’ –> empty line
‘param’ –> param line
‘pdesc’ –> description line for param
indent_n is number of spaces before text in line,
used for prepending ‘| ‘ to ensure manual line breaks are respected in sphinx format.
For blank lines, this is the indent_n of the next nonblank line.
For text lines, this is the minimum indent across all lines (except the first line).
For pdesc lines, this is the sub-indent level of the first desc line;
subsequent desc lines have the same indent_n.
(This makes the sphinx docs maintain the sub-indentation level as well!)
line is all the text in the line after removing indent_n spaces.
nonblank_line_here_or_next(i)
return self.lines[i] if nonblank, else first nonblank line after i.
param_ilines()
return dict of {i: [iline of all description lines]} for param lines in docstring.
param lines are those which match self.PARAM_PATTERN,
AND are not indented underneath an existing param line.
(also, line 0 is NEVER a param line, no matter what.)
line number) example line:
0) Example docstring
1) param1: is a param line
2) description line
3) param2: is another param line
4) description line
5) another description line
6) param 3: still not a param line (too indented)
7) param4: param line again
8) back to non-param line
9)
10) param5: param line again
11) description line again
12) going to talk about a subset of parameters now:
13) subparam1: param line
14) description line
15) subparam2: param line
16)
17) still non-paramline
–> result would be:
{1: [2], 3: [4, 5, 6], 7: [], 10: [11], 13: [14], 15: []}
to_sphinx()
returns self.docstring, converted to sphinx format.
See help(type(self)) for more details.

Equivalent: ‘n’.join(self.to_sphinx_lines())

to_sphinx_lines()
returns lines of self.docstring, converted to sphinx format.
See help(type(self)) for more details.

Equivalent: self.to_sphinx().split(’n’)