Module pdoc provides types and functions for accessing the public
documentation of a Python module. This includes module level
variables, modules (and sub-modules), functions, classes and class
and instance variables. Docstrings are taken from modules, functions,
and classes using special __doc__ attribute. Docstrings for any of
the variables are extracted by examining the module's abstract syntax
tree.
The public interface of a module is determined through one of two
ways. If __all__ is defined in the module, then all identifiers in
that list will be considered public. No other identifiers will be
considered as public. Conversely, if __all__ is not defined, then
pdoc will heuristically determine the public interface. There are two
simple rules that are applied to each identifier in the module:
If the name starts with an underscore, it is not public.
If the name is defined in a different module, it is not public.
If the name is a direct sub-module, then it is public.
Once documentation for a module is created, it can be outputted
in either HTML or plain text using the covenience functions
html and text, or the corresponding methods
html and text.
self, name, module, class_obj)
self)
self)
self)
self)
self)
var html_module_suffix
The suffix to use for module HTML files. By default, this is set to
.m.html, where the extra .m is used to differentiate a package's
index.html from a submodule called index.
var html_package_name
The file name to use for a package's __init__.py module.
var import_path
A list of paths to restrict imports to. Any module that cannot be
found in import_path will not be imported. By default, it is set to a
copy of sys.path at initialization.
var template_path
A list of paths to search for Mako templates used to produce the plain text and HTML output. Each path is tried until a template is found.
def html(
module_name, docfilter=None, allsubmodules=False, external_links=False, link_prefix='', source=True)
Returns the documentation for the module module_name in HTML
format. The module must be importable.
docfilter is an optional predicate that controls which
documentation objects are shown in the output. It is a single
argument function that takes a documentation object and returns
True or False. If False, that object will not be included in
the output.
If allsubmodules is True, then every submodule of this module
that can be found will be included in the documentation, regardless
of whether __all__ contains it.
If external_links is True, then identifiers to external modules
are always turned into links.
If link_prefix is True, then all links will have that prefix.
Otherwise, links are always relative.
If source is True, then source code will be retrieved for
every Python object whenever possible. This can dramatically
decrease performance when documenting large modules.
def import_module(
module_name)
A single point of truth for importing modules to be documented
by pdoc. In particular, it makes sure that the top module
in module_name can be imported by using only the paths in
import_path.
If a module has already been imported, then its corresponding entry
in sys.modules is returned. This means that modules that have
changed on disk cannot be re-imported in the same process and have
its documentation updated.
def text(
module_name, docfilter=None, allsubmodules=False)
Returns the documentation for the module module_name in plain
text format. The module must be importable.
docfilter is an optional predicate that controls which
documentation objects are shown in the output. It is a single
argument function that takes a documentation object and returns
True of False. If False, that object will not be included in the
output.
If allsubmodules is True, then every submodule of this module
that can be found will be included in the documentation, regardless
of whether __all__ contains it.
class Class
Representation of a class's documentation.
var cls
The class Python object.
var doc
A mapping from identifier name to a Doc objects.
var doc_init
A special version of doc that contains
documentation for instance variables found in the __init__
method.
var docstring
The docstring for this object. It has already been cleaned
by inspect.cleandoc.
var refname
Returns an appropriate reference name for this documentation object. Usually this is its fully qualified path. Every documentation object must provide this property.
e.g., The refname for this property is
pdoc.Doc.refname.
var source
Returns the source code for the underlying Python object as a list of lines. If the source code can't be retrieved, then the empty list is returned.
def __init__(
self, name, module, class_obj)
Same as pdoc.Doc)__init__, except class_obj must be a
Python class object. The docstring is gathered automatically.
def class_variables(
self)
Returns all documented class variables in the class, sorted
alphabetically as a list of Variable.
def functions(
self)
Returns all documented static functions as Function
objects in the class, sorted alphabetically.
def instance_variables(
self)
Returns all instance variables in the class, sorted
alphabetically as a list of Variable. Instance variables
are attributes of self defined in a class's __init__
method.
def is_empty(
self)
Returns true if the docstring for this object is empty.
def methods(
self)
Returns all documented methods as Function objects in
the class, sorted alphabetically with __new__ and __init__
always coming first.
Unfortunately, this also includes class methods.
class Doc
A base class for all documentation objects.
A documentation object corresponds to something in a Python module
that has a docstring associated with it. Typically, this only includes
modules, classes, functions and methods. However, pdoc adds support
for extracting docstrings from the abstract syntax tree, which means
that variables (module, class or instance) are supported too.
A special type of documentation object External is used to
represent identifiers that are not part of the public interface of
a module. (The name "External" is a bit of a misnomer, since it can
also correspond to unexported members of the module, particularly in
a class's ancestor list.)
var docstring
The docstring for this object. It has already been cleaned
by inspect.cleandoc.
var module
The module documentation object that this object was defined in.
var name
The identifier name for this object.
var refname
Returns an appropriate reference name for this documentation object. Usually this is its fully qualified path. Every documentation object must provide this property.
e.g., The refname for this property is
pdoc.Doc.refname.
var source
Returns the source code for the underlying Python object as a list of lines. If the source code can't be retrieved, then the empty list is returned.
def __init__(
self, name, module, docstring)
Initializes a documentation object, where name is the public
identifier name, module is a Module object, and
docstring is a string containing the docstring for name.
def is_empty(
self)
Returns true if the docstring for this object is empty.
class External
A representation of an external identifier. The textual representation is the same as an internal identifier, but without any context. (Usually this makes linking more difficult.)
External identifiers are also used to represent something that is not exported but appears somewhere in the public interface (like the ancestor list of a class).
var docstring
The docstring for this object. It has already been cleaned
by inspect.cleandoc.
var refname
Returns an appropriate reference name for this documentation object. Usually this is its fully qualified path. Every documentation object must provide this property.
e.g., The refname for this property is
pdoc.Doc.refname.
var source
Returns the source code for the underlying Python object as a list of lines. If the source code can't be retrieved, then the empty list is returned.
def __init__(
self, name)
Initializes an external identifier with name, where name
should be a fully qualified name.
class Function
Representation of documentation for a Python function or method.
var cls
The Class documentation object if this is a method. If
not, this is None.
var docstring
The docstring for this object. It has already been cleaned
by inspect.cleandoc.
var func
The Python function object.
var method
Whether this function is a method or not.
In particular, static class methods have this set to False.
var refname
Returns an appropriate reference name for this documentation object. Usually this is its fully qualified path. Every documentation object must provide this property.
e.g., The refname for this property is
pdoc.Doc.refname.
var source
Returns the source code for the underlying Python object as a list of lines. If the source code can't be retrieved, then the empty list is returned.
def __init__(
self, name, module, func_obj, cls=None, method=False)
Same as __init__, except func_obj must be a
Python function object. The docstring is gathered automatically.
cls should be set when this is a method or a static function
beloing to a class. cls should be a Class object.
method should be True when the function is a method. In
all other cases, it should be False.
def is_empty(
self)
Returns true if the docstring for this object is empty.
def params(
self)
Returns a list where each element is a nicely formatted parameter of this function. This includes argument lists, keyword arguments and default values.
def spec(
self)
Returns a nicely formatted spec of the function's parameter list as a string. This includes argument lists, keyword arguments and default values.
class Module
Representation of a module's documentation.
var doc
A mapping from identifier name to a documentation object.
var docstring
The docstring for this object. It has already been cleaned
by inspect.cleandoc.
var refdoc
The same as doc, but maps fully qualified
identifier names to documentation objects.
var refname
Returns an appropriate reference name for this documentation object. Usually this is its fully qualified path. Every documentation object must provide this property.
e.g., The refname for this property is
pdoc.Doc.refname.
var source
Returns the source code for the underlying Python object as a list of lines. If the source code can't be retrieved, then the empty list is returned.
def __init__(
self, module, docfilter=None, allsubmodules=False)
Creates a Module documentation object given the actual
module Python object.
docfilter is an optional predicate that controls which
documentation objects are returned in the following
methods: classes, functions,
variables and submodules. The
filter is propagated to the analogous methods on a Class
object.
If allsubmodules is True, then every submodule of this
module that can be found will be included in the
documentation, regardless of whether __all__ contains it.
def classes(
self)
Returns all documented module level classes in the module
sorted alphabetically as a list of Class.
def descendents(
self, cls)
def find_class(
self, cls)
Given a Python cls object, try to find it in this module
or in any of the exported identifiers of the submodules.
def find_ident(
self, name)
Searches this module and all of its sub-modules for an
identifier with name name in its list of exported
identifiers according to pdoc. Note that unexported
sub-modules are searched.
A bare identifier (without . separators) will only be checked
for in this module.
The documentation object corresponding to the identifier is
returned. If one cannot be found, then an instance of
External is returned populated with the given identifier.
def functions(
self)
Returns all documented module level functions in the module
sorted alphabetically as a list of Function.
def html(
self, external_links=False, link_prefix='', source=True, **kwargs)
Returns the documentation for this module as self-contained HTML.
If external_links is True, then identifiers to external
modules are always turned into links.
If link_prefix is True, then all links will have that
prefix. Otherwise, links are always relative.
If source is True, then source code will be retrieved for
every Python object whenever possible. This can dramatically
decrease performance when documenting large modules.
kwargs is passed to the mako render function.
def is_empty(
self)
Returns true if the docstring for this object is empty.
def is_package(
self)
Returns True if this module is a package.
Works by checking if __package__ is not None and whether it
has the __path__ attribute.
def is_public(
self, name)
Returns True if and only if an identifier with name name is
part of the public interface of this module. While the names
of sub-modules are included, identifiers only exported by
sub-modules are not checked.
name should be a fully qualified name, e.g.,
pdoc.Module.is_public.
def is_submodule(
self, name)
Returns True if and only if name starts with the full
import path of self and has length at least one greater than
len(self.name).
def mro(
self, cls)
def submodules(
self)
Returns all documented sub-modules in the module sorted
alphabetically as a list of Module.
def text(
self)
Returns the documentation for this module as plain text.
def variables(
self)
Returns all documented module level variables in the module
sorted alphabetically as a list of Variable.
class Variable
Representation of a variable's documentation. This includes module, class and instance variables.
var cls
The podc.Class object if this is a class or instance
variable. If not, this is None.
var docstring
The docstring for this object. It has already been cleaned
by inspect.cleandoc.
var refname
Returns an appropriate reference name for this documentation object. Usually this is its fully qualified path. Every documentation object must provide this property.
e.g., The refname for this property is
pdoc.Doc.refname.
var source
Returns the source code for the underlying Python object as a list of lines. If the source code can't be retrieved, then the empty list is returned.
def __init__(
self, name, module, docstring, cls=None)