pydoctor.epydoc2stan

module documentation

(source)

Convert pydoctor.epydoc parsed markup into renderable content.

Class	`Field`	Like `pydoctor.epydoc.markup.Field`, but without the gross accessor methods and with a formatted body.
Class	`FieldDesc`	Combines informations from multiple `Field` objects into one.
Class	`FieldHandler`	No class docstring; 0/13 instance variable, 2/22 methods, 0/1 static method documented
Class	`KeywordArgument`	Encapsulate the name of `kwarg` parameters.
Class	`ParsedStanOnly`	A `ParsedDocstring` directly constructed from stan, for caching purposes.
Class	`RaisesDesc`	Description of an exception that can be raised by function/method.
Class	`VariableArgument`	Encapsulate the name of `vararg` parameters.
Function	`colorized_pyval_fallback`	This fallback function uses `ParsedDocstring.to_node()`, so it must be used only with `ParsedDocstring` subclasses that implements `to_node()`.
Function	`ensure_parsed_docstring`	Currently, it's not 100% clear at what point the `Documentable.parsed_docstring` attribute is set. It can be set from the ast builder or later processing step.
Function	`extract_fields`	Populate Attributes for module/class variables using fields from that module/class's docstring. Must only be called for objects that have a docstring.
Function	`format_constant_value`	Should be only called for `Attribute` objects that have the `Attribute.value` property set.
Function	`format_desc_list`	Format list of `FieldDesc`. Used for param, returns, raises, etc.
Function	`format_docstring`	Generate an HTML representation of a docstring
Function	`format_docstring_fallback`	Undocumented
Function	`format_field_list`	Format list of `Field` object. Used for notes, see also, authors, etc.
Function	`format_kind`	Transform a `model.DocumentableKind` Enum value to string.
Function	`format_summary`	Generate an shortened HTML representation of a docstring.
Function	`format_summary_fallback`	Undocumented
Function	`format_toc`	Undocumented
Function	`format_undocumented`	Generate an HTML representation for an object lacking a docstring.
Function	`get_docstring`	Fetch the docstring for a documentable. Treat empty docstring as undocumented.
Function	`get_parsed_type`	Undocumented
Function	`get_parser`	Get the `parse_docstring(str, List[ParseError], bool) -> ParsedDocstring` function.
Function	`get_to_stan_error`	Undocumented
Function	`insert_break_points`	Browsers aren't smart enough to recognize word breaking opportunities in snake_case or camelCase, so this function helps them out by inserting word break opportunities.
Function	`parse_docstring`	Parse a docstring.
Function	`reportErrors`	Undocumented
Function	`reportWarnings`	Undocumented
Function	`safe_to_stan`	Wraps `ParsedDocstring.to_stan()` to catch exception and handle them in `fallback`. This is used to convert docstrings as well as other colorized AST values to stan.
Function	`type2stan`	Undocumented
Constant	`BROKEN`	Undocumented
Variable	`field_name_to_kind`	Undocumented
Function	`_format_constant_value`	Undocumented
Function	`_get_parsed_summary`	Ensures that the `model.Documentable.parsed_summary` attribute of a documentable is set to it's final value. Do not generate summary twice.
Function	`_is_none_literal`	Does this AST node represent the literal constant None?
Function	`_split_indentifier_parts_on_case`	Undocumented

def colorized_pyval_fallback(_, doc, __): (source) ¶

This fallback function uses ParsedDocstring.to_node(), so it must be used only with ParsedDocstring subclasses that implements to_node().

Parameters
_:`List[ParseError]`	Undocumented
doc:`ParsedDocstring`	Undocumented
__:`model.Documentable`	Undocumented
Returns
`Tag`	Undocumented

def ensure_parsed_docstring(obj): (source) ¶

Currently, it's not 100% clear at what point the Documentable.parsed_docstring attribute is set. It can be set from the ast builder or later processing step.

This function ensures that the parsed_docstring attribute of a documentable is set to it's final value.

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Optional[model.Documentable]`	If the `obj.parsed_docstring` is set to a `ParsedDocstring` instance: The source object of the docstring (might be different from `obj` if the documentation is inherited). If the object is undocumented: `None`.

def extract_fields(obj): (source) ¶

Populate Attributes for module/class variables using fields from that module/class's docstring. Must only be called for objects that have a docstring.

Parameters
obj:`model.Documentable`	Undocumented

def format_constant_value(obj): (source) ¶

Should be only called for Attribute objects that have the Attribute.value property set.

Parameters
obj:`model.Attribute`	Undocumented
Returns
`Flattenable`	Undocumented

def format_desc_list(label, descs): (source) ¶

Format list of FieldDesc. Used for param, returns, raises, etc.

Generates a 2-columns layout as follow:

    +------------------------------------+
    | <label>                            |
    | <name>: <type> |     <desc>        |
    | <name>: <type> |     <desc>        |
    +------------------------------------+

If the fields don't have type or name information, generates the same output as format_field_list:

    +------------------------------------+
    | <label>                            |
    | <desc ... >                        |
    +------------------------------------+

Parameters
label:`str`	Section "mini heading"
descs:`Sequence[FieldDesc]`	`FieldDesc`s
Returns
`Iterator[Tag]`	Each row as iterator or None if no `descs` id provided.

def format_docstring(obj): (source) ¶

Generate an HTML representation of a docstring

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Tag`	Undocumented

def format_docstring_fallback(errs, parsed_doc, ctx): (source) ¶

Undocumented

Parameters
errs:`List[ParseError]`	Undocumented
parsed_doc:`ParsedDocstring`	Undocumented
ctx:`model.Documentable`	Undocumented
Returns
`Tag`	Undocumented

def format_field_list(singular, plural, fields): (source) ¶

Format list of Field object. Used for notes, see also, authors, etc.

Generates a 2-columns layout as follow:

    +------------------------------------+
    | <label>                            |
    | <desc ... >                        |
    +------------------------------------+

Parameters
singular:`str`	Undocumented
plural:`str`	Undocumented
fields:`Sequence[Field]`	Undocumented
Returns
`Iterator[Tag]`	Each row as iterator

def format_kind(kind, plural=False): (source) ¶

Transform a `model.DocumentableKind` Enum value to string.

Parameters
kind:`model.DocumentableKind`	Undocumented
plural:`bool`	Undocumented
Returns
`str`	Undocumented

def format_summary(obj): (source) ¶

Generate an shortened HTML representation of a docstring.

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Tag`	Undocumented

def format_summary_fallback(errs, parsed_doc, ctx): (source) ¶

Undocumented

Parameters
errs:`List[ParseError]`	Undocumented
parsed_doc:`ParsedDocstring`	Undocumented
ctx:`model.Documentable`	Undocumented
Returns
`Tag`	Undocumented

def format_toc(obj): (source) ¶

Undocumented

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Optional[Tag]`	Undocumented

def format_undocumented(obj): (source) ¶

Generate an HTML representation for an object lacking a docstring.

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Tag`	Undocumented

def get_docstring(obj): (source) ¶

Fetch the docstring for a documentable. Treat empty docstring as undocumented.

:returns:

(docstring, source) if the object is documented.
(None, None) if the object has no docstring (even inherited).
(None, source) if the object has an empty docstring.

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Tuple[Optional[str], Optional[model.Documentable]]`	Undocumented

def get_parsed_type(obj): (source) ¶

Undocumented

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Optional[ParsedDocstring]`	Undocumented

def get_parser(obj): (source) ¶

Get the parse_docstring(str, List[ParseError], bool) -> ParsedDocstring function.

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Callable[[str, List[ParseError], bool], ParsedDocstring]`	Undocumented

def get_to_stan_error(e): (source) ¶

Undocumented

Parameters
e:`Exception`	Undocumented
Returns
`ParseError`	Undocumented

def insert_break_points(text): (source) ¶

Browsers aren't smart enough to recognize word breaking opportunities in snake_case or camelCase, so this function helps them out by inserting word break opportunities.

:note: It support full dotted names and will add a wbr tag after each dot.

Parameters
text:`str`	Undocumented
Returns
`Flattenable`	Undocumented

def parse_docstring(obj, doc, source, markup=None, section='docstring'): (source) ¶

Parse a docstring.

Parameters
obj:`model.Documentable`	The object we're parsing the documentation for.
doc:`str`	The docstring.
source:`model.Documentable`	The object on which the docstring is defined. This can differ from `obj` if the docstring is inherited.
markup:`Optional[str]`	Parse the docstring with the given markup, ignoring system's options. Useful for creating `ParsedDocstring`s from restructuredtext for instance.
section:`str`	A custom section to use.
Returns
`ParsedDocstring`	Undocumented

def reportErrors(obj, errs, section='docstring'): (source) ¶

Undocumented

Parameters
obj:`model.Documentable`	Undocumented
errs:`Sequence[ParseError]`	Undocumented
section:`str`	Undocumented

def reportWarnings(obj, warns, **kwargs): (source) ¶

Undocumented

Parameters
obj:`model.Documentable`	Undocumented
warns:`Sequence[str]`	Undocumented
**kwargs:`Any`	Undocumented

def safe_to_stan(parsed_doc, linker, ctx, compact, fallback, report=True, section='docstring'): (source) ¶

Wraps ParsedDocstring.to_stan() to catch exception and handle them in fallback. This is used to convert docstrings as well as other colorized AST values to stan.

Parameters
parsed_doc:`ParsedDocstring`	The `ParsedDocstring` to "stanify".
linker:`DocstringLinker`	The `DocstringLinker` to use to resolve links.
ctx:`model.Documentable`	The documentable context to use to report errors, passed to the `fallback` function.
compact:`bool`	Whether the generated html should be compact.
fallback:`Callable[[List[ParseError], ParsedDocstring, model.Documentable], Tag]`	A callable that returns a fallback stan if the convertion failed. It can also be used to set some state on the documentable context. Signature: (errs:List[ParseError], doc:ParsedDocstring, ctx:model.Documentable) -> Tag
report:`bool`	Whether to report errors.
section:`str`	Used for error messages.
Returns
`Tag`	Undocumented

def type2stan(obj): (source) ¶

Undocumented

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Optional[Tag]`	Undocumented

BROKEN = (source) ¶

Undocumented

Value

tags.p(class_='undocumented')('Broken description')

field_name_to_kind = (source) ¶

Undocumented

def _format_constant_value(obj): (source) ¶

Undocumented

Parameters
obj:`model.Attribute`	Undocumented
Returns
`Iterator[Flattenable]`	Undocumented

def _get_parsed_summary(obj): (source) ¶

Ensures that the model.Documentable.parsed_summary attribute of a documentable is set to it's final value. Do not generate summary twice.

Parameters
obj:`model.Documentable`	Undocumented
Returns
`Tuple[Optional[model.Documentable], ParsedDocstring]`	Tuple: `source`, `parsed docstring`

def _is_none_literal(node): (source) ¶

Does this AST node represent the literal constant None?

Parameters
node:`ast.expr`	Undocumented
Returns
`bool`	Undocumented

def _split_indentifier_parts_on_case(indentifier): (source) ¶

Undocumented

Parameters
indentifier:`str`	Undocumented
Returns
`List[str]`	Undocumented