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, 3/22 methods, 0/1 static method documented
Class FieldOrigin Undocumented
Class KeywordArgument Encapsulate the name of kwarg parameters in Function.annotations mapping keys.
Class KeywordDesc Undocumented
Class ParamDesc Undocumented
Class ParamType Undocumented
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 ReturnDesc Undocumented
Class VariableArgument Encapsulate the name of vararg parameters in Function.annotations mapping keys.
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_constructor_short_text Returns a simplified signature of the constructor. forclass is not always the function's parent, it can be a subclass.
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_parsed_type Get the type of this attribute as parsed docstring.
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 populate_constructors_extra_info Adds an extra information to be rendered based on Class constructors.
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 Get the formatted type of this attribute.
Function unwrap_docstring_stan Unwrap the body of the given Tag instance if it has a non-empty tag name and ensure there is at least one paragraph.
Constant BROKEN Undocumented
Variable field_name_to_kind Undocumented
Class _SignatureDesc Undocumented
Function _format_constant_value Undocumented
Function _get_docformat Returns the docformat to use to parse the docstring of this object.
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 _split_indentifier_parts_on_case Undocumented
Function _wrap_in_paragraph Whether to wrap the given docstring stan body inside a paragraph.
Variable _docformat_skip_processtypes Undocumented
def colorized_pyval_fallback(_: list[ParseError], doc: ParsedDocstring, __: model.Documentable) -> Tag: (source)

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

def ensure_parsed_docstring(obj: model.Documentable) -> model.Documentable | None: (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.

Returns
model.Documentable | None
  • 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: model.CanContainImportsDocumentable): (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.

def format_constant_value(obj: model.Attribute) -> Flattenable: (source)

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

def format_constructor_short_text(constructor: model.Function, forclass: model.Class) -> str: (source)

Returns a simplified signature of the constructor. forclass is not always the function's parent, it can be a subclass.

def format_desc_list(label: str, descs: Sequence[FieldDesc]) -> Iterator[Tag]: (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:strSection "mini heading"
descs:Sequence[FieldDesc]FieldDescs
Returns
Iterator[Tag]Each row as iterator or None if no descs id provided.
def format_docstring(obj: model.Documentable) -> Tag: (source)

Generate an HTML representation of a docstring

def format_docstring_fallback(errs: list[ParseError], parsed_doc: ParsedDocstring, ctx: model.Documentable) -> Tag: (source)

Undocumented

def format_field_list(singular: str, plural: str, fields: Sequence[Field]) -> Iterator[Tag]: (source)

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

Generates a 2-columns layout as follow:

    +------------------------------------+
    | <label>                            |
    | <desc ... >                        |
    +------------------------------------+
Returns
Iterator[Tag]Each row as iterator
def format_kind(kind: model.DocumentableKind, plural: bool = False) -> str: (source)

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

def format_summary(obj: model.Documentable) -> Tag: (source)

Generate an shortened HTML representation of a docstring.

def format_summary_fallback(errs: list[ParseError], parsed_doc: ParsedDocstring, ctx: model.Documentable) -> Tag: (source)

Undocumented

def format_toc(obj: model.Documentable) -> Tag | None: (source)

Undocumented

def format_undocumented(obj: model.Documentable) -> Tag: (source)

Generate an HTML representation for an object lacking a docstring.

def get_parsed_type(obj: model.Documentable) -> ParsedDocstring | None: (source)

Get the type of this attribute as parsed docstring.

def get_to_stan_error(e: Exception) -> ParseError: (source)

Undocumented

def insert_break_points(text: str) -> Flattenable: (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.

def parse_docstring(obj: model.Documentable, doc: str, source: model.Documentable, markup: str | None = None, section: str = 'docstring') -> ParsedDocstring: (source)

Parse a docstring.

Parameters
obj:model.DocumentableThe object we're parsing the documentation for.
doc:strThe docstring.
source:model.DocumentableThe object on which the docstring is defined. This can differ from obj if the docstring is inherited.
markup:str | NoneParse the docstring with the given markup, ignoring system's options. Useful for creating ParsedDocstrings from restructuredtext for instance.
section:strA custom section to use.
Returns
ParsedDocstringUndocumented
def populate_constructors_extra_info(cls: model.Class): (source)

Adds an extra information to be rendered based on Class constructors.

def reportErrors(obj: model.Documentable, errs: Sequence[ParseError], section: str = 'docstring'): (source)

Undocumented

def reportWarnings(obj: model.Documentable, warns: Sequence[str], **kwargs: Any): (source)

Undocumented

def safe_to_stan(parsed_doc: ParsedDocstring, linker: DocstringLinker, ctx: model.Documentable, fallback: Callable[[list[ParseError], ParsedDocstring, model.Documentable], Tag], report: bool = True, section: str = 'docstring') -> Tag: (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:ParsedDocstringThe ParsedDocstring to "stanify".
linker:DocstringLinkerThe DocstringLinker to use to resolve links.
ctx:model.DocumentableThe documentable context to use to report errors, passed to the fallback function.
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:boolWhether to report errors.
section:strUsed for error messages.
Returns
TagUndocumented
def type2stan(obj: model.Documentable) -> Tag | None: (source)

Get the formatted type of this attribute.

def unwrap_docstring_stan(stan: Tag) -> Flattenable: (source)

Unwrap the body of the given Tag instance if it has a non-empty tag name and ensure there is at least one paragraph.

Note

This is the counterpart of what we're doing in HTMLTranslator.should_be_compact_paragraph(). Since the HTMLTranslator is generic for all parsed docstrings types, it always generates compact paragraphs.

But for docstrings, we want to have at least one paragraph for consistency.

BROKEN = (source)

Undocumented

Value
tags.p(class_='undocumented')('Broken description')
field_name_to_kind = (source)

Undocumented

def _format_constant_value(obj: model.Attribute) -> Iterator[Flattenable]: (source)

Undocumented

def _get_docformat(obj: model.Documentable) -> str: (source)

Returns the docformat to use to parse the docstring of this object.

def _get_parsed_summary(obj: model.Documentable) -> tuple[model.Documentable | None, ParsedDocstring]: (source)

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

Returns
tuple[model.Documentable | None, ParsedDocstring]Tuple: source, parsed docstring
def _split_indentifier_parts_on_case(indentifier: str) -> list[str]: (source)

Undocumented

def _wrap_in_paragraph(body: Sequence[Flattenable]) -> bool: (source)

Whether to wrap the given docstring stan body inside a paragraph.

_docformat_skip_processtypes: tuple[str, ...] = (source)

Undocumented