module documentation

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-autopackage" script, which is: Copyright 2008 Société des arts technologiques (SAT), https://sat.qc.ca/

Unknown Field: copyright
Copyright 2007-2022 by the Sphinx team, see AUTHORS.
Unknown Field: license
BSD, see LICENSE for details.
Constant OPTIONS Undocumented
Constant PY​_SUFFIXES Undocumented
Variable template​_dir Undocumented
Function create​_module​_file Build the text of the file and write the file.
Function create​_modules​_toc​_file Create the module's index.
Function create​_package​_file Build the text of the file and write the file.
Function get​_parser Undocumented
Function has​_child​_module Check the given directory contains child module/s (at least one).
Function is​_excluded Check if the directory is in the exclude list.
Function is​_initpy Check filename is __init__ file or not.
Function is​_packagedir Check given files contains __init__ file.
Function is​_skipped​_module Check if we want to skip this module.
Function is​_skipped​_package Check if we want to skip this module.
Function main Parse and check the command line arguments.
Function module​_join Join module names with dots.
Function recurse​_tree Look for every file in the directory tree and create the corresponding ReST files.
Function walk Walk through the directory and list files and subdirectories up.
Function write​_file Write the output file for module/package <name>.
OPTIONS =

Undocumented

Value
os.environ['SPHINX_APIDOC_OPTIONS'].split(',')
PY_SUFFIXES =

Undocumented

Value
('.py', '.pyx')+tuple(EXTENSION_SUFFIXES)
template_dir =

Undocumented

def create_module_file(package, basename, opts, user_template_dir=None):
Build the text of the file and write the file.
Parameters
package:strUndocumented
basename:strUndocumented
opts:AnyUndocumented
user​_template​_dir:strUndocumented
def create_modules_toc_file(modules, opts, name='modules', user_template_dir=None):
Create the module's index.
Parameters
modules:List[str]Undocumented
opts:AnyUndocumented
name:strUndocumented
user​_template​_dir:strUndocumented
def create_package_file(root, master_package, subroot, py_files, opts, subs, is_namespace, excludes=[], user_template_dir=None):
Build the text of the file and write the file.
Parameters
root:strUndocumented
master​_package:strUndocumented
subroot:strUndocumented
py​_files:List[str]Undocumented
opts:AnyUndocumented
subs:List[str]Undocumented
is​_namespace:boolUndocumented
excludes:List[str]Undocumented
user​_template​_dir:strUndocumented
def get_parser():

Undocumented

Returns
argparse.ArgumentParserUndocumented
def has_child_module(rootpath, excludes, opts):
Check the given directory contains child module/s (at least one).
Parameters
rootpath:strUndocumented
excludes:List[str]Undocumented
opts:AnyUndocumented
Returns
boolUndocumented
def 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 exclude "foo" also accidentally excluding "foobar".
Parameters
root:strUndocumented
excludes:List[str]Undocumented
Returns
boolUndocumented
def is_initpy(filename):
Check filename is __init__ file or not.
Parameters
filename:strUndocumented
Returns
boolUndocumented
def is_packagedir(dirname=None, files=None):
Check given files contains __init__ file.
Parameters
dirname:strUndocumented
files:List[str]Undocumented
Returns
boolUndocumented
def is_skipped_module(filename, opts, excludes):
Check if we want to skip this module.
Parameters
filename:strUndocumented
opts:AnyUndocumented
excludes:List[str]Undocumented
Returns
boolUndocumented
def is_skipped_package(dirname, opts, excludes=[]):
Check if we want to skip this module.
Parameters
dirname:strUndocumented
opts:AnyUndocumented
excludes:List[str]Undocumented
Returns
boolUndocumented
def main(argv=sys.argv[1:]):
Parse and check the command line arguments.
Parameters
argv:List[str]Undocumented
Returns
intUndocumented
def module_join(*modnames):
Join module names with dots.
Parameters
*modnames:strUndocumented
Returns
strUndocumented
def recurse_tree(rootpath, excludes, opts, user_template_dir=None):
Look for every file in the directory tree and create the corresponding ReST files.
Parameters
rootpath:strUndocumented
excludes:List[str]Undocumented
opts:AnyUndocumented
user​_template​_dir:strUndocumented
Returns
List[str]Undocumented
def walk(rootpath, excludes, opts):
Walk through the directory and list files and subdirectories up.
Parameters
rootpath:strUndocumented
excludes:List[str]Undocumented
opts:AnyUndocumented
Returns
Generator[Tuple[str, List[str], List[str]], None, None]Undocumented
def write_file(name, text, opts):
Write the output file for module/package <name>.
Parameters
name:strUndocumented
text:strUndocumented
opts:AnyUndocumented