ModAPIDocumenter

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

Bases: sphinx.ext.autodoc.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, ...)

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([ignore])

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: Dict[str, Callable[[str], Any]] = {'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-inheritance-diagram': <function bool_option>, 'no-main-docstring': <function bool_option>, 'no-toctree': <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: Optional[docutils.statemachine.StringList], 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
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: Union[List[sphinx.ext.autodoc.ObjectMember], List[Tuple[str, Any]]], 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: Optional[docutils.statemachine.StringList] = None, real_modname: Optional[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(ignore: Optional[int] = None) Optional[List[List[str]]]

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, sphinx.ext.autodoc.ObjectMember]

Get members of target module.

get_object_members(want_all: bool) Tuple[bool, Union[List[sphinx.ext.autodoc.ObjectMember], List[Tuple[str, Any]]]]

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, parents: Any, path: str, base: Any) Tuple[str, 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[sphinx.ext.autodoc.Documenter, bool]], order: str) List[Tuple[sphinx.ext.autodoc.Documenter, bool]]

Sort the given member list.