Package lucidoc Documentation

Class DocTag

Representation of a tag within a docstring

def __init__(self, typename, description)

Initialize self. See help(type(self)) for accurate signature.

def description(self)

Described value to which this tag pertains

Returns:

• str: description of value being tagged

def typename(self)

Get the name of the type(s) associated with the tag

Returns:

• str: Text of either single type name or union of several

Class DocstringParser

Entity responsible for parsing docstrings

def description(self, ds)

Parse the description portion of a docstring.

Parameters:

• ds (str): docstring from which to parse description

Returns:

• str: description portion of docstring

def params(self, ds)

Parse parameter tags from docstring.

Parameters:

• ds (str): docstring from which to parse parameter tags

Returns:

• Iterable[lucidoc.ParTag]: (possibly empty) collection ofparameter tags parsed from the given docstring

def raises(self, ds)

Parse parameter tags from docstring.

Parameters:

• ds (str): docstring from which to parse result tag

Returns:

• Iterable[lucidoc.ErrTag]: (possibly empty) collection ofparameter tags parsed from the given docstring

def returns(self, ds)

Parse parameter tags from docstring.

Parameters:

• ds (str): docstring from which to parse result tag

Returns:

• lucidoc.RetTag | NoneType: (possibly empty) collection ofparameter tags parsed from the given docstring

Class DocstringStyler

How to style/render docstrings

Class ErrTag

Tag for type and description of a potential Exception

def description(self)

Described value to which this tag pertains

Returns:

• str: description of value being tagged

def typename(self)

Get the name of the type(s) associated with the tag

Returns:

• str: Text of either single type name or union of several

Class LucidocError

Base error type for this package

Class MdTagRenderer

Render tag for Markdown

Class ParTag

Representation of a parameter tag in docstring

def __init__(self, name, typename, description)

Create a parameter tag with a name, typename, and description.

Parameters:

• name (str): the formal parameter name
• typename (``): text describing valid argument types
• description (``): detail about the parameter and/or accepted args

def description(self)

Described value to which this tag pertains

Returns:

• str: description of value being tagged

def name(self)

Get the parameter name.

Returns:

• str: The parameter name for this tag

def typename(self)

Get the name of the type(s) associated with the tag

Returns:

• str: Text of either single type name or union of several

Class ParsedDocstringResult

ParsedDocstringResult(doc, desc, params, returns, raises, examples)

def desc(self)

Alias for field number 1

def doc(self)

Alias for field number 0

def examples(self)

Alias for field number 5

def params(self)

Alias for field number 2

def raises(self)

Alias for field number 4

def returns(self)

Alias for field number 3

Class PycodeDocstringStyler

Style/render docstring by wrapping it in Python code block fences.

Class RetTag

Tag for type and description of return value

def description(self)

Described value to which this tag pertains

Returns:

• str: description of value being tagged

def typename(self)

Get the name of the type(s) associated with the tag

Returns:

• str: Text of either single type name or union of several

Class RstDocstringParser

Parser for ReStructured text docstrings.

def __init__(self)

Set the most recently seen docstring parse result to null.

def description(self, ds)

Parse the description portion of a docstring.

Parameters:

• ds (str): docstring from which to parse description

Returns:

• str: description portion of docstring

def examples(self, ds)

Get the code example text from a docstring.

Parameters:

• ds (str): docstring from which to parse example

Returns:

• str: code example text from docstring

def params(self, ds)

Parse parameter tags from docstring.

Parameters:

• ds (str): docstring from which to parse parameter tags

Returns:

• Iterable[lucidoc.ParTag]: (possibly empty) collection ofparameter tags parsed from the given docstring

def raises(self, ds)

Parse parameter tags from docstring.

Parameters:

• ds (str): docstring from which to parse result tag

Returns:

• Iterable[lucidoc.ErrTag]: (possibly empty) collection ofparameter tags parsed from the given docstring

def returns(self, ds)

Parse parameter tags from docstring.

Parameters:

• ds (str): docstring from which to parse result tag

Returns:

• lucidoc.RetTag | NoneType: (possibly empty) collection ofparameter tags parsed from the given docstring

Class TagRenderer

Strategy for rendering a tag.

def doc_callable(f, docstr_parser, render_tag, name=None)

For single function get text components for Markdown documentation.

Parameters:

• f (callable | property): function or property to document
• docstr_parser (lucidoc.DocstringParser): How to parse a docstring.
• render_tag (callable(lucidoc.DocTag) -> str): how to render anindividual tag from a docstring. The implementation in the object passed as an argument should handle each type of DocTag that may be passed as an argument when this object is called.
• name (str): name of object being documented; pass directly for prop.

Returns:

• list[str]: text chunks constituting Markdown documentation forsingle function.

def doc_class(cls, docstr_parser, render_tag, include_inherited, nested=False)

For single class definition, get text components for Markdown documentation.

Parameters:

• cls (class): class to document with Markdown
• docstr_parser (lucidoc.DocstringParser): How to parse a docstring.
• render_tag (callable(lucidoc.DocTag) -> str): how to render anindividual tag from a docstring. The implementation in the object passed as an argument should handle each type of DocTag that may be passed as an argument when this object is called.
• include_inherited (bool): include inherited members
• nested (bool): whether the given target is nested within another class

Returns:

• list[str]: text chunks constituting Markdown documentation forsingle class definition.

def doc_module(mod, docstr_parser, render_tag, no_mod_docstr=False, include_inherited=False, retain=None, groups=None, omit_meta=False)

Get large block of Markdown-formatted documentation of a module

Parameters:

• mod (module): module to document in Markdown.
• docstr_parser (lucidoc.DocstringParser): how to parse a docstring.
• render_tag (callable(lucidoc.DocTag) -> str): how to render a tagparsed from a docstring; the argument should be total. In other words, each potential type of tag that may be passed to it as an argument should be accounted for in the implementation.
• no_mod_docstr (bool): skip module-level docstring
• include_inherited (bool): include inherited members
• retain (callable): positive selection (on/by name) of doc targets
• groups (Mapping[str, str | Iterable[str]] | Iterable[(str, str | Iterable[str])]): pairing of group name with either single target name or collection of target names
• omit_meta (bool): whether the version metadata for documentationtarget and for this package should be omitted from the documentation that's created

Returns:

• str | Mapping[str, str]: Large block of Markdown-formatteddocumentation; alternatively, a mapping between group name and documentation block for the objects from that group

Raises:

• TypeError: if retention strategy is provided but is not callable

def get_parser(name)

Get a docstring parsing strategy.

Parameters:

• name (str): Key for a parsing strategy.

Returns:

• lucidoc.DocstringParser: The parser to which the given name ismapped.

Raises:

• lucidoc.UnknownParserError: If given a nonempty name that's notmapped to a parser.

def get_styler(name)

Get a docstring styling strategy.

Parameters:

• name (str): name/key of desired styling strategy

Returns:

• lucidoc.DocstringStyler: styler to which given name is mapped.

Raises:

• lucidoc.UnknownStylerError: if given a nonempty name that's notmapped to a styler.

def run_lucidoc(pkg, parse_style, outfile=None, outfolder=None, no_mod_docstr=False, include_inherited=False, whitelist=None, blacklist=None, groups=None, omit_meta=False, **log_kwargs)

Discover docstrings and create package API documentation in Markdown.

Parameters:

• pkg (str): name of the package to document
• parse_style (str): key/name of parsing strategy to use
• outfile (str): path to documentation output file
• outfolder (str): path to folder in which to place docs output
• no_mod_docstr (bool): whether to exclude the module-level docstring,if present
• include_inherited (bool): whether to document inherited members
• whitelist (Iterable[str]): names of doc targets to include
• blacklist (Iterable[str]): names of doc targets to exclude
• groups (Mapping[str, str | Iterable[str]] | Iterable[(str, str | Iterable[str])]): pairing of group name with either single target name or collection of target names
• omit_meta (bool): whether the version metadata for documentationtarget and for this package should be omitted from the documentation that's created

Raises:

• TypeError: if passing an argument to whitelist or blacklist that'snot a non-string collection, or if passing an argument to groups in which a group's names isn't a non-string collection
• LucidocError: if passing both output file and output folder, or ifpassing output file and using groups; or if using more than one of whitelist, blacklist, and groups
• pydoc.ErrorDuringImport: if the argument to the package parameter(pkg) cannot be imported

Version Information: lucidoc v0.4.4, generated by lucidoc v0.4.4