jinjaapidoc.gendoc

This is a modification of sphinx.apidoc by David.Zuber. It uses jinja templates to render the rst files.

Parses a directory tree looking for Python modules and packages and creates ReST files appropriately to create code documentation with Sphinx.

This is derived form the “sphinx-apidoc” script, which is:

Copyright 2007-2014 by the Sphinx team, see http://sphinx-doc.org/latest/authors.html.

Functions

create_module_file(app, env, package, …) Build the text of the file and write the file.
create_package_file(app, env, root_package, …) Build the text of the file and write the file.
generate(app, src, dest[, exclude, …]) Generage the rst files
get_context(app, package, module, fullname) Return a dict for template rendering
get_members(app, mod, typ[, include_public]) Return the members of mod of the given type
get_submodules(app, module) Get all submodules without packages for the given module/package
get_subpackages(app, module) Get all subpackages for the given module/package
import_name(app, name) Import the given name and return name, obj, parent, mod_name
is_excluded(root, excludes) Check if the directory is in the exclude list.
main(app) Parse the config of the app and initiate the generation process
make_environment(loader) Return a new jinja2.Environment with the given loader
make_loader(template_dirs) Return a new jinja2.FileSystemLoader that uses the template_dirs
makename(package, module) Join package and module with a dot.
normalize_excludes(excludes) Normalize the excluded directory list.
prepare_dir(app, directory[, delete]) Create apidoc dir, delete contents if delete is True.
recurse_tree(app, env, src, dest, excludes, …) Look for every file in the directory tree and create the corresponding ReST files.
shall_skip(app, module, private) Check if we want to skip this module.
write_file(app, name, text, dest, suffix, …) Write the output file for module/package <name>.

Data

AUTOSUMMARYTEMPLATE_DIR Templates for autosummary
INITPY str(object=’‘) -> string
MODULE_TEMPLATE_NAME Name of the template that is used for rendering modules.
PACKAGE_TEMPLATE_NAME Name of the template that is used for rendering packages.
PY_SUFFIXES set() -> new empty set object set(iterable) -> new set object
TEMPLATE_DIR Built-in template dir for jinjaapi rendering
logger LoggerAdapter allowing type and subtype keywords.
jinjaapidoc.gendoc.create_module_file(app, env, package, module, dest, suffix, dryrun, force)[source]

Build the text of the file and write the file.

Parameters:
  • app (sphinx.application.Sphinx) – the sphinx app
  • env (jinja2.Environment) – the jinja environment for the templates
  • package (str) – the package name
  • module (str) – the module name
  • dest (str) – the output directory
  • suffix (str) – the file extension
  • dryrun (bool) – If True, do not create any files, just log the potential location.
  • force (bool) – Overwrite existing files
Returns:

None
Raises:

None
jinjaapidoc.gendoc.create_package_file(app, env, root_package, sub_package, private, dest, suffix, dryrun, force)[source]

Build the text of the file and write the file.

Parameters:
  • app (sphinx.application.Sphinx) – the sphinx app
  • env (jinja2.Environment) – the jinja environment for the templates
  • root_package (str) – the parent package
  • sub_package (str) – the package name without root
  • private (bool) – Include “_private” modules
  • dest (str) – the output directory
  • suffix (str) – the file extension
  • dryrun (bool) – If True, do not create any files, just log the potential location.
  • force (bool) – Overwrite existing files
Returns:

None
Raises:

None
jinjaapidoc.gendoc.generate(app, src, dest, exclude=[], followlinks=False, force=False, dryrun=False, private=False, suffix='rst', template_dirs=None)[source]

Generage the rst files

Raises an OSError if the source path is not a directory.

Parameters:
  • app (sphinx.application.Sphinx) – the sphinx app
  • src (str) – path to python source files
  • dest (str) – output directory
  • exclude (list) – list of paths to exclude
  • followlinks (bool) – follow symbolic links
  • force (bool) – overwrite existing files
  • dryrun (bool) – do not create any files
  • private (bool) – include “_private” modules
  • suffix (str) – file suffix
  • template_dirs (None | list) – directories to search for user templates
Returns:

None
Return type:

None
Raises:

OSError
jinjaapidoc.gendoc.get_context(app, package, module, fullname)[source]

Return a dict for template rendering

Variables:

  • package:The top package
  • module:the module
  • fullname:package.module
  • subpkgs:packages beneath module
  • submods:modules beneath module
  • classes:public classes in module
  • allclasses:public and private classes in module
  • exceptions:public exceptions in module
  • allexceptions:public and private exceptions in module
  • functions:public functions in module
  • allfunctions:public and private functions in module
  • data:public data in module
  • alldata:public and private data in module
  • members:dir(module)
Parameters:
Returns:

a dict with variables for template rendering
Return type:

dict
Raises:

None
jinjaapidoc.gendoc.get_members(app, mod, typ, include_public=None)[source]

Return the members of mod of the given type

Parameters:
  • app (sphinx.application.Sphinx) – the sphinx app
  • mod (module) – the module with members
  • typ (str) – the typ, 'class', 'function', 'exception', 'data', 'members'
  • include_public (list | None) – list of private members to include to publics
Returns:

None
Return type:

None
Raises:

None
jinjaapidoc.gendoc.get_submodules(app, module)[source]

Get all submodules without packages for the given module/package

Parameters:
Returns:

list of module names excluding packages
Return type:

list
Raises:

TypeError
jinjaapidoc.gendoc.get_subpackages(app, module)[source]

Get all subpackages for the given module/package

Parameters:
Returns:

list of packages names
Return type:

list
Raises:

TypeError
jinjaapidoc.gendoc.import_name(app, name)[source]

Import the given name and return name, obj, parent, mod_name

Parameters:name (str) – name to import
Returns:the imported object or None
Return type:object | None
Raises:None
jinjaapidoc.gendoc.is_excluded(root, excludes)[source]

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”.
jinjaapidoc.gendoc.main(app)[source]

Parse the config of the app and initiate the generation process

Parameters:app (sphinx.application.Sphinx) – the sphinx app
Returns:None
Return type:None
Raises:None
jinjaapidoc.gendoc.make_environment(loader)[source]

Return a new jinja2.Environment with the given loader

Parameters:loader (jinja2.BaseLoader) – a jinja2 loader
Returns:a new environment
Return type:jinja2.Environment
Raises:None
jinjaapidoc.gendoc.make_loader(template_dirs)[source]

Return a new jinja2.FileSystemLoader that uses the template_dirs

Parameters:template_dirs (None | list) – directories to search for templates
Returns:a new loader
Return type:jinja2.FileSystemLoader
Raises:None
jinjaapidoc.gendoc.makename(package, module)[source]

Join package and module with a dot.

Package or Module can be empty.

Parameters:
  • package (str) – the package name
  • module (str) – the module name
Returns:

the joined name
Return type:

str
Raises:

AssertionError, if both package and module are empty
jinjaapidoc.gendoc.normalize_excludes(excludes)[source]

Normalize the excluded directory list.

jinjaapidoc.gendoc.prepare_dir(app, directory, delete=False)[source]

Create apidoc dir, delete contents if delete is True.

Parameters:
  • app (sphinx.application.Sphinx) – the sphinx app
  • directory (str) – the apidoc directory. you can use relative paths here
  • delete (bool) – if True, deletes the contents of apidoc. This acts like an override switch.
Returns:

None
Return type:

None
Raises:

None
jinjaapidoc.gendoc.recurse_tree(app, env, src, dest, excludes, followlinks, force, dryrun, private, suffix)[source]

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

Parameters:
  • app (sphinx.application.Sphinx) – the sphinx app
  • env (jinja2.Environment) – the jinja environment
  • src (str) – the path to the python source files
  • dest (str) – the output directory
  • excludes (list) – the paths to exclude
  • followlinks (bool) – follow symbolic links
  • force (bool) – overwrite existing files
  • dryrun (bool) – do not generate files
  • private (bool) – include “_private” modules
  • suffix (str) – the file extension
jinjaapidoc.gendoc.shall_skip(app, module, private)[source]

Check if we want to skip this module.

Parameters:
jinjaapidoc.gendoc.write_file(app, name, text, dest, suffix, dryrun, force)[source]

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

Parameters:
  • app (sphinx.application.Sphinx) – the sphinx app
  • name (str) – the file name without file extension
  • text (str) – the content of the file
  • dest (str) – the output directory
  • suffix (str) – the file extension
  • dryrun (bool) – If True, do not create any files, just log the potential location.
  • force (bool) – Overwrite existing files
Returns:

None
Raises:

None
jinjaapidoc.gendoc.AUTOSUMMARYTEMPLATE_DIR = 'autosummarytemplates'

Templates for autosummary

jinjaapidoc.gendoc.INITPY = '__init__.py'

str(object=’‘) -> string

Return a nice string representation of the object. If the argument is a string, the return value is the same object.

jinjaapidoc.gendoc.MODULE_TEMPLATE_NAME = 'jinjaapi_module.rst'

Name of the template that is used for rendering modules.

jinjaapidoc.gendoc.PACKAGE_TEMPLATE_NAME = 'jinjaapi_package.rst'

Name of the template that is used for rendering packages.

jinjaapidoc.gendoc.PY_SUFFIXES = set(['.py', '.pyx'])

set() -> new empty set object set(iterable) -> new set object

Build an unordered collection of unique elements.

jinjaapidoc.gendoc.TEMPLATE_DIR = 'templates'

Built-in template dir for jinjaapi rendering

jinjaapidoc.gendoc.logger = <sphinx.util.logging.SphinxLoggerAdapter object>

LoggerAdapter allowing type and subtype keywords.