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 (case-insensitive)

‘Example’, ‘Examples’, ‘Return’, ‘Returns’, ‘Equivalent’,

- currently, no other fancy-formatting is recognized.

- (this might be updated eventually)

- some patterns will be replaced:

* –> \* # to avoid sphinx interpreting as “emphasis”

** –> \*\* # to avoid sphinx interpreting as “strong emphasis”

* –> * # (use 3 asterisks instead of 1, to emphasize something)

** –> ** # (use 4 asterisks instead of 2, to strongly emphasize something)

|x| –> \|x| # to avoid sphinx interpreting as “substitution”.

x –> `x` # to tell sphinx to interpret as “code”

word_ –> word_ # avoid sphinx thinking word is a reference to something.

If you don’t like all the details of “custom” format, you can just use sphinx format.

Methods

from_obj(obj)	return DocstringInfo(obj.__doc__)
get_indent_n(line)	returns number of leading spaces in line.
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.
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.
to_sphinx()	returns self.docstring, converted to sphinx format.
to_sphinx_lines()	returns lines of self.docstring, converted to sphinx format.
_custom_to_sphinx_lines()	convert custom docstring to sphinx format.
_infer_base_indent()	return minimum indent across all lines except the first.
_reconstruct()	reconstruct docstring from self.line_infos().

Attributes

KNOWN_SPHINX_PATTERN
NEVER_PARAMS
PARAM_PATTERN

_custom_to_sphinx_lines()

convert custom docstring to sphinx format.

assumes but does not check self.kind==’custom’.

_infer_base_indent()

return minimum indent across all lines except the first.

if only nonblank line is the first line, return 0.

_reconstruct()

reconstruct docstring from self.line_infos().

Mainly for debugging purposes.

[TODO] result has extra (or not enough?) whitespace compared to docstring,

but only differs in blank lines, so not a big deal.

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’)