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[plasmapy_sphinx.automodsumm.generate.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: Optional[str] = None) List[plasmapy_sphinx.automodsumm.generate.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: Optional[str] = None, suffix: str = '.rst', base_path: Optional[str] = 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().