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 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_summary Generate a string representation for an object lacking a docstring.
Function function_signature_len The lenght of the a function def is defnied by the lenght of it's name plus the lenght of it's signature. On top of that, a function or method that takes no argument (expect unannotated 'self' for methods, and 'cls' for classmethods) will always have a lenght equals to the function name len plus two for 'function()'.
Function get_constructors_extra Get an extra docstring to represent Class constructors.
Function get_namespace_docstring Get a useful description about this namespace package.
Function get_parsed_signature Undocumented
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 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
Constant BROKEN_TEXT Undocumented
Variable field_name_to_kind Undocumented
Class _SignatureDesc Undocumented
Function _colorize_signature Colorize this signature into a ParsedDocstring.
Function _colorize_signature_annotation Returns this annotation as a list of nodes
Function _colorize_signature_param Convert a single parameter to a docutils inline element.
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 _is_less_important_param Whether this parameter is the 'self' param of methods or 'cls' param of class methods.
Function _objclass Undocumented
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]) -> list[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
list[Tag]A list containing a single table tag or an empty list if no descs are 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]) -> list[Tag]: (source)

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

Generates a 2-columns layout as follow:

    +------------------------------------+
    | <label>                            |
    | <desc ... >                        |
    +------------------------------------+
Returns
list[Tag]A list containing a single table tag or an empty list if no fields are provided.
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_summary(obj: model.Documentable) -> str: (source)

Generate a string representation for an object lacking a docstring.

def function_signature_len(func: model.Function | model.FunctionOverload) -> int: (source)

The lenght of the a function def is defnied by the lenght of it's name plus the lenght of it's signature. On top of that, a function or method that takes no argument (expect unannotated 'self' for methods, and 'cls' for classmethods) will always have a lenght equals to the function name len plus two for 'function()'.

def get_constructors_extra(cls: model.Class) -> ParsedDocstring | None: (source)

Get an extra docstring to represent Class constructors.

def get_namespace_docstring(ns: model.Package) -> str: (source)

Get a useful description about this namespace package.

def get_parsed_signature(func: model.Function | model.FunctionOverload) -> ParsedDocstring | None: (source)

Undocumented

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 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_TEXT)
BROKEN_TEXT: str = (source)

Undocumented

Value
'Broken description'
field_name_to_kind = (source)

Undocumented

def _colorize_signature(sig: inspect.Signature, ctx: model.Documentable) -> ParsedDocstring: (source)

Colorize this signature into a ParsedDocstring.

def _colorize_signature_annotation(annotation: object) -> list[nodes.Node]: (source)

Returns this annotation as a list of nodes

def _colorize_signature_param(param: inspect.Parameter, ctx: model.Documentable, has_next: bool, is_first: bool) -> nodes.inline: (source)

Convert a single parameter to a docutils inline element.

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 _is_less_important_param(param: inspect.Parameter, ctx: model.Documentable) -> bool: (source)

Whether this parameter is the 'self' param of methods or 'cls' param of class methods.

Note
this does not check whether the parameter is the first of the signature. This should be done before calling this function!
def _objclass(obj: model.Documentable) -> ObjClass | None: (source)

Undocumented

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