granite.sphinx module

Provides the main DocBuilder class for easily interfacing with sphinx to build the project’s documentation.

class DocBuilder

Bases: object

Provides a simple interface for consistently building documentation.

By default, this class will generate the API docs using sphinx’s apidoc script, overwriting any existing API .rst files (provided the API_OUTPUT_DIR attribute has been set. Afterward, sphinx itself is run on the project.

Projects are expected to create a file named build_docs.py (or something similar) within the docs directory of your project that contains a subclass of this class, instantiate it, then run its build method. An example:

import os
import sys

THIS_DIR = os.path.dirname(__file__)
sys.path.insert(0, os.path.join(THIS_DIR, '..', '..', 'src'))
from granite.sphinx import DocBuilder


def mkpath(*parts):
    """Makes an abspath from THIS_DIR"""
    return os.path.normpath(os.path.join(THIS_DIR, *parts))


class Builder(DocBuilder):
    # input path
    SOURCE_DIR = mkpath('source')
    # output path
    BUILD_DIR = mkpath('build')
    # remove this line if auto-api generation is not desired
    API_OUTPUT_DIR = mkpath('source', 'api')
    # the path to the python package
    PROJECT_DIR = mkpath('..', 'src', 'granite')

    FILES_TO_CLEAN = [
        API_OUTPUT_DIR,
        BUILD_DIR,
    ]


if __name__ == '__main__':
    Builder().build()

Each of the following attributes should be defined in order to configure DcoBuilder. Each attribute that is a path should be an absolute path.

SOURCE_DIR

str – the path to the project’s source directory

BUILD_DIR

str – the path to the documentation output

API_OUTPUT_DIR

str – defining this will automatically call sphinx-apidoc on the project directory. See the generate_api_docs() method for more information. Optional

PROJECT_DIR

str – path to the directory containing Python project.

FILES_TO_CLEAN

List[str] – a list of files to clean when --clean is passed on the command line. Optional

API_EXCLUDE_DIRS

List[str] – a list of paths relative to PROJECT_DIR to exclude from the api-doc generation.

API_EXCLUDE_DIRS = []

API_OUTPUT_DIR = ''

BUILD_DIR = ''

FILES_TO_CLEAN = []

PROJECT_DIR = ''

SOURCE_DIR = ''

add_argument(*args, **kwargs)

Add an argument to the ArgumentParser in self.parser.

Takes in the same args and kwargs as the ArgumentParser.add_argument() method. Use this method in order to add custom flags to the argument parsing. The argv flags are parsed in the build() method. This sets the parsed args into self.args and the leftover unknown flags into self.argv.

build(argv=None)

Gathers all command line arguments and then builds the docs.

This performs command line parsing and stores the known flags (those added with self.add_argument()) into self.args and all leftover unknown args into self.argv (see argparse.ArgumentParser.parse_known_args() for more information on the types of each).

After argparsing the following three methods are called in this order:

• pre_build_hook()
• generate_documentation()
• post_build_hook()

Override the pre and post build hooks in order to add custom checks or other functionality.

Parameters:argv (List[str]) – command line flags to parse; defaults to sys.argv

generate_api_docs()

Generates the API documentation for all of the packages/modules/classes/functions.

Sphinx doesn’t automatically generate the documentation for the api. This calls sphinx-apidoc which will create the API .rst files and dump them in the source directory. It is expected that one of the TOC directives calls out to the created API directory.

Note: if the attribute API_OUTPUT_DIR is not set on this class, then this method does nothing.

generate_documentation()

Runs sphinx on the project using the default conf.py file in the source directory.

post_build_hook()

This is called immediately after all documentation has been generated.

Override this method for any custom functionality.

pre_build_hook()

This is called after all arguments have been collected, but before sphinx is called.

Override this method for any custom functionality.

safe_delete(filename)

Tries to delete filename and ignores any error that is raised.

setup_default_arguments()

This method adds some default command line parameters.

Current, the default flags are:

• --clean: Cleans all files found in the FILES_TO_CLEAN

  list.

try_clean()

Attempts to clean all of the files found in self.FILES_TO_CLEAN.

Ignores all errors.

exception RequiredAttributeException(attribute, class_, description)

Bases: granite.exceptions.GraniteException

Raised when an attribute on the DocBuilder class has not been defined