multipackage.data.scripts.better_apidocs module

better apidoc

Parses a directory tree looking for Python modules and packages and creates ReST files appropriately to create code documentation with Sphinx. It also creates a modules index (named modules.<suffix>).

This is derived from the “sphinx-apidoc” script, which is: Copyright 2007-2016 by the Sphinx team http://www.sphinx-doc.org

It extends “sphinx-apidoc” by the –template / -t option, which allows to render the output ReST files based on arbitrary Jinja templates.

copyright:Copyright 2017-2018 by Michael Goerz license:BSD, see LICENSE for details.

Summary

Functions:

add_get_members_to_template_env
create_module_file	Generate RST for a top-level module (i.e., not part of a package)
create_modules_toc_file	Create the module’s index.
create_package_file	Build the text of the file and write the file.
extract_summary	Extract summary from docstring.
format_directive	Create the automodule directive and add the options.
format_heading	Create a heading of <level> [1, 2 or 3 supported].
is_excluded	Check if the directory is in the exclude list.
main	Parse and check the command line arguments.
makename	Join package and module with a dot.
normalize_excludes	Normalize the excluded directory list.
recurse_tree	Look for every file in the directory tree and create the corresponding ReST files.
shall_skip	Check if we want to skip this module.
write_file	Write the output file for module/package <name>.

Data:

EXTENSIONS	Dictionary that remembers insertion order
INITPY	str(object=’‘) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
OPTIONS	list() -> new empty list list(iterable) -> new list initialized from iterable’s items
PY_SUFFIXES	set() -> new empty set object set(iterable) -> new set object
periods_re	Compiled regular expression objects
state_classes	tuple() -> empty tuple tuple(iterable) -> tuple initialized from iterable’s items

Reference

multipackage.data.scripts.better_apidocs.makename(package, module)

Join package and module with a dot.

multipackage.data.scripts.better_apidocs.write_file(name, text, opts)

Write the output file for module/package <name>.

multipackage.data.scripts.better_apidocs.format_heading(level, text)

Create a heading of <level> [1, 2 or 3 supported].

multipackage.data.scripts.better_apidocs.format_directive(module, package=None)

Create the automodule directive and add the options.

multipackage.data.scripts.better_apidocs.create_module_file(package, module, opts)

Generate RST for a top-level module (i.e., not part of a package)

multipackage.data.scripts.better_apidocs.extract_summary(obj)

Extract summary from docstring.

multipackage.data.scripts.better_apidocs.add_get_members_to_template_env(template_env, fullname, opts)

multipackage.data.scripts.better_apidocs.create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace)

Build the text of the file and write the file.

multipackage.data.scripts.better_apidocs.create_modules_toc_file(modules, opts, name='modules')

Create the module’s index.

multipackage.data.scripts.better_apidocs.shall_skip(module, opts)

Check if we want to skip this module.

multipackage.data.scripts.better_apidocs.recurse_tree(rootpath, excludes, opts)

Look for every file in the directory tree and create the corresponding ReST files.

multipackage.data.scripts.better_apidocs.normalize_excludes(rootpath, excludes)

Normalize the excluded directory list.

multipackage.data.scripts.better_apidocs.is_excluded(root, excludes)

Check if the directory is in the exclude list.

Note: by having trailing slashes, we avoid common prefix issues, like

e.g. an exlude “foo” also accidentally excluding “foobar”.

multipackage.data.scripts.better_apidocs.main(argv=['/home/travis/virtualenv/python3.6.7/bin/sphinx-build', '-W', '-E', '-b', 'html', '.multipackage/scripts/../../.tmp_docs', '.multipackage/scripts/../../built_docs'])

Parse and check the command line arguments.