class documentation

An object that can be documented.

The interface is a bit ridiculously wide.

Method __init__ Undocumented
Method __repr__ Undocumented
Method docsources Objects that can be considered as a source of documentation.
Method expandName Return a fully qualified name for the possibly-dotted `name`.
Method fullName Undocumented
Method isNameDefined Is the given name defined in the globals/locals of self-context? Only the first name of a dotted name is checked.
Method reparent Undocumented
Method report Log an error or warning about this documentable object.
Method resolveName Return the object named by "name" (using Python's lookup rules) in this context, if any is known to pydoctor.
Method setDocstring Undocumented
Method setLineNumber Save the linenumber of this object.
Method setup Undocumented
Class Variable kind Page location where we are documented.
Class Variable parsed_docstring Undocumented
Class Variable parsed_summary Undocumented
Class Variable parsed_type Undocumented
Instance Variable contents Undocumented
Instance Variable docstring The object's docstring. But also see docsources.
Instance Variable docstring_lineno Undocumented
Instance Variable extra_info A list to store extra informations about this documentable, as ParsedDocstring.
Instance Variable linenumber Undocumented
Instance Variable name Undocumented
Instance Variable parent Undocumented
Instance Variable parentMod Undocumented
Instance Variable source_path Undocumented
Instance Variable sourceHref Undocumented
Instance Variable system The system the object is part of.
Property description A string describing our source location to the user.
Property docstring_linker Returns an instance of DocstringLinker suitable for resolving names in the context of the object.
Property doctarget Undocumented
Property isPrivate Is this object considered private API?
Property isVisible Is this object so private as to be not shown at all?
Property module This object's Module.
Property page_object The documentable to which the page we're documented on belongs. For example methods are documented on the page of their class, functions are documented in their module's page etc.
Property privacyClass How visible this object should be.
Property url Relative URL at which the documentation for this Documentable can be found.
Method _handle_reparenting_post Undocumented
Method _handle_reparenting_pre Undocumented
Method _localNameToFullName Undocumented
Instance Variable _linker Undocumented
def __init__(self, system: System, name: str, parent: Documentable | None = None, source_path: Path | None = None): (source)

Undocumented

def __repr__(self) -> str: (source)

Undocumented

def docsources(self) -> Iterator[Documentable]: (source)

Objects that can be considered as a source of documentation.

The motivating example for having multiple sources is looking at a superclass' implementation of a method for documentation for a subclass'.

def expandName(self, name: str) -> str: (source)

Return a fully qualified name for the possibly-dotted `name`.

To explain what this means, consider the following modules:

mod1.py:

    from external_location import External
    class Local:
        pass

mod2.py:

    from mod1 import External as RenamedExternal
    import mod1 as renamed_mod
    class E:
        pass

In the context of mod2.E, expandName("RenamedExternal") should be "external_location.External" and expandName("renamed_mod.Local") should be "mod1.Local".

def fullName(self) -> str: (source)

Undocumented

def isNameDefined(self, name: str) -> bool: (source)

Is the given name defined in the globals/locals of self-context? Only the first name of a dotted name is checked.

Returns True iff the given name can be loaded without raising `NameError`.

def reparent(self, new_parent: Module, new_name: str): (source)

Undocumented

def report(self, descr: str, section: str = 'parsing', lineno_offset: int = 0, thresh: int = -1): (source)

Log an error or warning about this documentable object.

Parameters
descr:strThe error/warning string
section:strWhat the warning is about.
lineno_offset:intOffset
thresh:intThresh to pass to System.msg, it will use -1 by default, meaning it will count as a violation and will fail the build if option -W is passed. But this behaviour is not applicable if thresh is greater or equal to zero.
def resolveName(self, name: str) -> Documentable | None: (source)

Return the object named by "name" (using Python's lookup rules) in this context, if any is known to pydoctor.

def setDocstring(self, node: astutils.Str): (source)

Undocumented

def setLineNumber(self, lineno: LineFromDocstringField | LineFromAst | int): (source)

Save the linenumber of this object.

If the linenumber is already set from a ast analysis, this is an no-op. If the linenumber is already set from docstring fields and the new linenumber if not from docstring fields as well, the old docstring based linumber will be replaced with the one from ast analysis since this takes precedence.

Parameters
lineno:LineFromDocstringField | LineFromAst | intThe linenumber. If the given linenumber is simply an int we'll assume it's coming from the ast builder and it will be converted to an LineFromAst instance.

Page location where we are documented.

parsed_docstring: ParsedDocstring | None = (source)

Undocumented

Undocumented

Undocumented

Undocumented

docstring: str | None = (source)

The object's docstring. But also see docsources.

docstring_lineno = (source)

Undocumented

A list to store extra informations about this documentable, as ParsedDocstring.

Undocumented

Undocumented

parentMod: Module | None = (source)

Undocumented

source_path: Path | None = (source)

Undocumented

sourceHref: str | None = (source)

Undocumented

The system the object is part of.

@property
description: str = (source)

A string describing our source location to the user.

If this module's code was read from a file, this returns its file path. In other cases, such as during unit testing, the full module name is returned.

Returns an instance of DocstringLinker suitable for resolving names in the context of the object.

Undocumented

Is this object considered private API?

This is just a simple helper which defers to self.privacyClass.

Is this object so private as to be not shown at all?

This is just a simple helper which defers to self.privacyClass.

overridden in pydoctor.model.Module

This object's Module.

For modules, this returns the object itself, otherwise the module containing the object is returned.

The documentable to which the page we're documented on belongs. For example methods are documented on the page of their class, functions are documented in their module's page etc.

overridden in pydoctor.model.Module

How visible this object should be.

Relative URL at which the documentation for this Documentable can be found.

For page objects this method MUST return an .html filename without a URI fragment (because pydoctor.templatewriter.writer.TemplateWriter uses it directly to determine the output filename).

def _handle_reparenting_post(self): (source)

Undocumented

def _handle_reparenting_pre(self): (source)

Undocumented

def _localNameToFullName(self, name: str) -> str: (source)