autodoc_ext package

Module contents

autodoc_ext.templates.generate_docs_dir(source_dir, build_dir)

Generate the information required to build Docs

Parameters

  • source_dir – Directory of the source

  • build_dir – Build/Docs directory relative to source_dir

Returns

artifacts that were created

autodoc_ext.templates.generate_modules_rst(package, directory)

Generate the base modules.rst file

Parameters

  • package – name of th software package

  • directory – location where the artifacts will be placed.

Returns

name/path of the generated file

autodoc_ext.templates.generate_rst(tree, directory='.')

Generate the rst files for the tree

Parameters

  • tree – Node class that is used to generate rst documents.

  • directory – Output directory for all rst documents.

Returns

Dictionary of artifacts that were created

autodoc_ext.templates.generate_sphinx(*args, **kwargs)

Find all .j2 extension files in this directory. Fill the template files with the parameters that were passed in to this function. See args.check_args for default values. The following artifacts will be placed into the SOURCE_DIR: - Makefile: see Makefile.j2 - make.bat: see make.bat.j2 - conf.py: see conf.py.j2 - index.rst: see index.rst.j2

Parameters

  • PROJECT – Name of the project that the documents are generated for.

  • COPYRIGHT – Year of the copyright for the PROJECT.

  • AUTHOR – Author(s) of the PROJECT as a single string.

  • VERSION – Version of the PROJECT.

  • EXTENSIONS – Extension packages that can be combined with sphinx.

  • TEMPLATES – Path(s) containing templates.

  • EXCLUSIONS – Path(s) and patterns of files to exclude from docs.

  • THEME – The theme to use for HTML and HTML Help pages.

  • STATIC_PATHS – Path(s) that contain custom static files.

  • SOURCE_DIR – Directory for the source of the software package.

  • BUILD_DIR – Directory where the sphinx build will occur.

Returns

List of files that were generated

autodoc_ext.args.check_args(*args, **kwargs)

Check the arguments to ensure that the following parameters are passed and contain the correct type. If the type is not correctly formatted and can be formatted it will be altered, otherwise the data is reset to a proper empty value.

Parameters

  • PROJECT – Name of the project that the documents are generated for.

  • COPYRIGHT – Year of the copyright for the PROJECT.

  • AUTHOR – Author(s) of the PROJECT as a single string.

  • VERSION – Version of the PROJECT.

  • EXTENSIONS – Extension packages that can be combined with sphinx.

  • TEMPLATES – Path(s) containing templates.

  • EXCLUSIONS – Path(s) and patterns of files to exclude from docs.

  • THEME – The theme to use for HTML and HTML Help pages.

  • STATIC_PATHS – Path(s) that contain custom static files.

  • SOURCE_DIR – Directory for the source of the software package.

  • BUILD_DIR – Directory where the sphinx build will occur.

Returns

dictionary formatted with the arguments above, if they did not

exist in kwargs, defaults will be applied.

autodoc_ext.args.list_arg_format(list_of_values, expected_types)

Check that each value in list_of_values matches the expected_types. If the list of values is a primitive or simple type, it will be wrapped in a list and returned.

Parameters

  • list_of_values – List of values of expected types.

  • expected_types – tuple of types to be used for verification

Returns

List of values that matched the expected_types.

autodoc_ext.args.simple_arg_format(value, expected_types, default)

Check that the value is of an expected type. If it is not, use the default value:

Parameters

  • value – Value to be checked

  • expected_types – tuple of types to be used for verification

  • default – value used when value is not of expected_types.

Returns

value if matching expected types otherwise default

autodoc_ext.artifacts.destroy(source_dir)

Read the artifacts file from the source directory. All of the artifacts that are logged in the file (known objects) will be destroyed. The labels in the file designated keep will be kept as part of the destruction.

Parameters

source_dir – Source directory where the artifacts file will reside.

Returns

True when the data was successfully removed, false otherwise

autodoc_ext.artifacts.log_artifacts(source_dir, artifacts, hide_file=True)

Create build process logs/artifacts that will be used for during the destruction/cleanup process. The name of the file will be autodoc_ext_artifacts.yaml.

Parameters

  • source_dir – Source directory where the artifaces file will reside.

  • artifacts – Dictionary of created artifacts.

  • hide_file – When true [default], hide the artifacts file.

class autodoc_ext.tree.Node(name, path=None)

A node or leaf of an entire tree. The Node/leaf will contain the information located in a directory (including files, classes, subdirectories, path).

property all_filenames

Get all filenames (including path) contained in this instance

Returns

Instance files with path

property classes

Get the list of classes found in the files of this instance

Returns

List of classes that were found in the files of this tree.

property json

JSON formatted dictionary object for this node

Returns

json formatted dictionary for this instance.

project_files(filenames)

Get the project files without the extension.

Parameters

filenames – list of filenames in this instance.

Returns

Dictionary of full filename along with the formatted name.

property public_filenames

Get all filenames (including path) contained in this instance that are not prefaced with an underscore.

Returns

Instance files with path

autodoc_ext.tree.generate_tree(directory='.', parent=0)

Generate the tree by walking the directory structure and creating a node for each directory that has been found.

Parameters

  • directory – Directory where all files for the project will reside.

  • parent – parent directory depth.

Returns

A tree (Node) containing all information from the directory walk

class autodoc_ext.__main__.LogColorFormatter(fmt=None, datefmt=None, style='%')

Create a logging formatter to color and format the log output

FORMATS = {10: '\x1b[34;20m[%(levelname)s]: %(message)s\x1b[0m', 20: '\x1b[32;20m[%(levelname)s]: %(message)s\x1b[0m', 30: '\x1b[33;20m[%(levelname)s]: %(message)s\x1b[0m', 40: '\x1b[31;20m[%(levelname)s]: %(message)s\x1b[0m', 50: '\x1b[35;20m[%(levelname)s]: %(message)s\x1b[0m'}
blue = '\x1b[34;20m'
converter()
localtime([seconds]) -> (tm_year,tm_mon,tm_mday,tm_hour,tm_min,

tm_sec,tm_wday,tm_yday,tm_isdst)

Convert seconds since the Epoch to a time tuple expressing local time. When ‘seconds’ is not passed in, convert the current time instead.

default_msec_format = '%s,%03d'
default_time_format = '%Y-%m-%d %H:%M:%S'
format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

formatException(ei)

Format and return the specified exception information as a string.

This default implementation just uses traceback.print_exception()

formatMessage(record)
formatStack(stack_info)

This method is provided as an extension point for specialized formatting of stack information.

The input data is a string as returned from a call to traceback.print_stack(), but with the last trailing newline removed.

The base implementation just returns the value passed in.

formatTime(record, datefmt=None)

Return the creation time of the specified LogRecord as formatted text.

This method should be called from format() by a formatter which wants to make use of a formatted time. This method can be overridden in formatters to provide for any specific requirement, but the basic behaviour is as follows: if datefmt (a string) is specified, it is used with time.strftime() to format the creation time of the record. Otherwise, an ISO8601-like (or RFC 3339-like) format is used. The resulting string is returned. This function uses a user-configurable function to convert the creation time to a tuple. By default, time.localtime() is used; to change this for a particular formatter instance, set the ‘converter’ attribute to a function with the same signature as time.localtime() or time.gmtime(). To change it for all formatters, for example if you want all logging times to be shown in GMT, set the ‘converter’ attribute in the Formatter class.

green = '\x1b[32;20m'
purple = '\x1b[35;20m'
red = '\x1b[31;20m'
reset = '\x1b[0m'
usesTime()

Check if the format uses the creation time of the record.

yellow = '\x1b[33;20m'
class autodoc_ext.tree.Node(name, path=None)

A node or leaf of an entire tree. The Node/leaf will contain the information located in a directory (including files, classes, subdirectories, path).

property all_filenames

Get all filenames (including path) contained in this instance

Returns

Instance files with path

property classes

Get the list of classes found in the files of this instance

Returns

List of classes that were found in the files of this tree.

property json

JSON formatted dictionary object for this node

Returns

json formatted dictionary for this instance.

project_files(filenames)

Get the project files without the extension.

Parameters

filenames – list of filenames in this instance.

Returns

Dictionary of full filename along with the formatted name.

property public_filenames

Get all filenames (including path) contained in this instance that are not prefaced with an underscore.

Returns

Instance files with path