GenDocsFromAutomodsumm

class plasmapy_sphinx.automodsumm.generate.GenDocsFromAutomodsumm

Bases: object

Class used for stub file generation from automodapi and automodsumm. An instance of the class is connected to the Sphinx event builder-inited, which is emitted when the builder object is created.

Attributes Summary

app

Instance of the Sphinx application.

logger

Instance of the SphinxLoggerAdapter for report during builds.

Methods Summary

__call__(app)

Scan through source files, check for the automodsumm and automodapi directives, and auto generate any associated stub files.

event_handler__autodoc_skip_member(app,Β ...)

Event handler for the Sphinx event autodoc-skip-member.

find_in_files(filenames)

Search files for the automodapi and automodsumm directives and generate a list of AutomodsummEntry's indicating which stub files need to be generated.

find_in_lines(lines[,Β filename])

Search a list of strings for the automodapi and automodsumm directives and generate a list of AutomodsummEntry's indicating which stub files need to be generated.

generate_docs(source_filenames[,Β ...])

Generate and write stub files for objects defined in the automodapi and automodsumm directives.

Attributes Documentation

app: 'Sphinx' = None

Instance of the Sphinx application.

logger = <SphinxLoggerAdapter sphinx.plasmapy_sphinx.automodsumm.generate (DEBUG)>

Instance of the SphinxLoggerAdapter for report during builds.

Methods Documentation

__call__(app: Sphinx)

Scan through source files, check for the automodsumm and automodapi directives, and auto generate any associated stub files.

Parameters:

app (Sphinx) – Instance of the Sphinx application.

Note

Adapted from sphinx.ext.autosummary.process_generate_options().

static event_handler__autodoc_skip_member(app: Sphinx, what: str, name: str, obj: Any, skip: bool, options: dict)

Event handler for the Sphinx event autodoc-skip-member. This handler ensures the __call__ method is documented if defined by the associated class.

find_in_files(filenames: List[str]) → List[AutomodsummEntry]

Search files for the automodapi and automodsumm directives and generate a list of AutomodsummEntry’s indicating which stub files need to be generated.

Parameters:

filenames (List[str]) – List of filenames to be searched.

Note

Adapted from sphinx.ext.autosummary.generate.find_autosummary_in_files().

find_in_lines(lines: List[str], filename: str | None = None) → List[AutomodsummEntry]

Search a list of strings for the automodapi and automodsumm directives and generate a list of AutomodsummEntry’s indicating which stub files need to be generated.

Parameters:

  • lines (List[str]) – List of strings to be searched.

  • filename (str) – The file from which lines came from.

Note

Adapted from sphinx.ext.autosummary.generate.find_autosummary_in_lines().

generate_docs(source_filenames: List[str], output_dir: str | None = None, suffix: str = '.rst', base_path: str | None = None, imported_members: bool = False, overwrite: bool = True, encoding: str = 'utf-8') → None

Generate and write stub files for objects defined in the automodapi and automodsumm directives.

Parameters:

  • source_filenames (List[str]) – A list of all filenames for with the automodapi and automodsumm directives will be searched for.

  • output_dir (str) – Directory for which the stub files will be written to.

  • suffix (str) – (Default ".rst") Suffix given to the written stub files.

  • base_path (str) – The common base path for the filenames listed in source_filenames. This is typically the source directory of the Sphinx application.

  • imported_members (bool) – (Default False) Set True to include imported members in the stub file documentation for module object types.

  • overwrite (bool) – (Default True) Will cause existing stub files to be overwritten.

  • encoding (str) – (Default: "utf-8") Encoding for the written stub files.

Note

Adapted from sphinx.ext.autosummary.generate.generate_autosummary_docs().