ModAPIDocumenter

class plasmapy_sphinx.autodoc.automodapi.ModAPIDocumenter(*args: Any)

Bases: ModuleDocumenter

The class that defines the autodoc directive automodapi.

Attributes Summary

content_indent	indentation by which to indent the directive content
directivetype	Defines the generated directive name.
documenters	Returns registered Documenter classes
grouping_info	Dictionary of automodapi and automodsumm group information.
logger	Instance of the SphinxLoggerAdapter for report during builds.
member_order	order if autodoc_member_order is set to 'groupwise'
objtype	Defines the auto directive name.
option_spec	Mapping of option names to validator functions.
priority	priority if multiple documenters return True from can_document_member
titles_allowed	true if the generated content may contain titles

Methods Summary

add_content(more_content[, no_docstring])	Add content from docstrings, attribute documentation and user.
add_directive_header(sig)	Add the directive header and options to the generated content.
add_line(line, source, *lineno)	Append one line of generated reST to the output.
can_document_member(member, membername, ...)	Called to see if a member can be documented by this Documenter.
check_module()	Check if self.object is really defined in the module given by self.modname.
document_members([all_members])	Generate reST for member documentation.
filter_members(members, want_all)	Filter the given member list.
format_args(**kwargs)	Format the argument signature of self.object.
format_name()	Format the name of self.object.
format_signature(**kwargs)	Format the signature (arguments and return annotation) of the object.
generate([more_content, real_modname, ...])	Generate reST for the object given by self.name, and possibly for its members.
generate_heading(modname)	Generate and place a heading at the top of the directive's content.
generate_more_content(modname)	Generate the "more content" associate with the automodsumm tables and inheritance diagrams.
get_attr(obj, name, *defargs)	getattr() override for types such as Zope interfaces.
get_doc()	Decode and return lines of the docstring(s) for the object.
get_module_members()	Get members of target module.
get_object_members(want_all)	Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.
get_real_modname()	Get the real module name of an object to document.
get_sourcename()
import_object([raiseerror])	Import the object given by self.modname and self.objpath and set it as self.object.
parse_name()	Determine what module to import and what attribute to document.
process_doc(docstrings)	Let the user process the docstrings before adding them.
resolve_name(modname, parents, path, base)	Resolve the module and name of the object to document given by the arguments and the current module/class.
sort_members(documenters, order)	Sort the given member list.

Attributes Documentation

content_indent = ''

indentation by which to indent the directive content

directivetype = 'module'

Defines the generated directive name. In this case .. :py:module::.

documenters

Returns registered Documenter classes

grouping_info

Dictionary of automodapi and automodsumm group information. The primary key is the group name, e.g. modules, classes, etc. The value associated with the primary key is a dictionary with the following keys:

title	Title used to head the automodsumm table.
description	Brief description to follow the title.
dunder	Name of the dunder variable used to define a custom group.

logger = <SphinxLoggerAdapter sphinx.plasmapy_sphinx.autodoc.automodapi (DEBUG)>

Instance of the SphinxLoggerAdapter for report during builds.

member_order = 0

order if autodoc_member_order is set to ‘groupwise’

objtype = 'modapi'

Defines the auto directive name. In this case automodapi.

option_spec: OptionSpec = {'deprecated': <function bool_option>, 'exclude-groups': <function option_str_list>, 'groups': <function option_str_list>, 'heading-chars': <function unchanged>, 'include-heading': <function bool_option>, 'inheritance-diagram': <function bool_option>, 'no-groups': <function bool_option>, 'no-index': <function bool_option>, 'no-inheritance-diagram': <function bool_option>, 'no-main-docstring': <function bool_option>, 'no-toctree': <function bool_option>, 'no-value': <function bool_option>, 'noindex': <function bool_option>, 'platform': <function identity>, 'show-inheritance': <function bool_option>, 'skip': <function option_str_list>, 'synopsis': <function identity>, 'toctree': <function unchanged>}

Mapping of option names to validator functions.

priority = 0

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

Methods Documentation

add_content(more_content: StringList | None, no_docstring: bool = False) → None

Add content from docstrings, attribute documentation and user.

add_directive_header(sig: str) → None

Add the directive header and options to the generated content.

add_line(line: str, source: str, *lineno: int) → None

Append one line of generated reST to the output.

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) → bool

Called to see if a member can be documented by this Documenter.

check_module() → bool

Check if self.object is really defined in the module given by self.modname.

document_members(all_members: bool = False) → None

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

filter_members(members: list[ObjectMember], want_all: bool) → list[tuple[str, Any, bool]]

Filter the given member list.

Members are skipped if

• they are private (except if given explicitly or the private-members option is set)

• they are special methods (except if given explicitly or the special-members option is set)

• they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

format_args(**kwargs: Any) → str

Format the argument signature of self.object.

Should return None if the object does not have a signature.

format_name() → str

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

format_signature(**kwargs: Any) → str

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

generate(more_content: StringList | None = None, real_modname: str = None, check_module: bool = False, all_members: bool = False) → None

Generate reST for the object given by self.name, and possibly for its members.

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

generate_heading(modname: str) → None

Generate and place a heading at the top of the directive’s content. If modname is a package then the title will be <modname> Package; and if a module (.py file) then the title will be <modname> Module.

Parameters:

modname (str) – Name of the module being documented (i.e. that given to automodapi).

generate_more_content(modname: str) → List[str]

Generate the “more content” associate with the automodsumm tables and inheritance diagrams.

Parameters:

modname (str) – Name of the module being documented (i.e. that given to automodapi).

Returns:

A list of strings to be added the to the directive’s content.

Return type:

List[str]

get_attr(obj: Any, name: str, *defargs: Any) → Any

getattr() override for types such as Zope interfaces.

get_doc() → list[list[str]] | None

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

get_module_members() → dict[str, ObjectMember]

Get members of target module.

get_object_members(want_all: bool) → tuple[bool, list[ObjectMember]]

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

get_real_modname() → str

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

get_sourcename() → str

import_object(raiseerror: bool = False) → bool

Import the object given by self.modname and self.objpath and set it as self.object.

Returns True if successful, False if an error occurred.

parse_name() → bool

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

process_doc(docstrings: list[list[str]]) → Iterator[str]

Let the user process the docstrings before adding them.

resolve_name(modname: str | None, parents: Any, path: str, base: str) → tuple[str | None, list[str]]

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

sort_members(documenters: list[tuple[Documenter, bool]], order: str) → list[tuple[Documenter, bool]]

Sort the given member list.