autodoc module

This module provides a class to create documentation automatically.

exception autodoc.SphinxError

Bases: Exception

Exception raised when creating, building, or generating Sphinx docs.

class autodoc.SphinxProject(package_dir, project_dir)

Bases: object

Representation of a Sphinx project.

__init__(package_dir, project_dir)

Initialize the Sphinx project object.

Parameters:

• package_dir (str) – The path to the package to document.

• project_dir (str) – The path to the Sphinx project or where it should be saved.

build(clean=False)

Build the Sphinx project.

Parameters:

clean (bool) – If True a clean build will be created.

Raises:

• ValueError – Raised if the project and/or package does not exist.

• SphinxError – Raised if an error occured during the build.

create(author, project_name=None, version='1')

Create a new Sphinx project.

Parameters:

• author (str) – Name of the package author.

• project_name (str) – Name of the project that is displayed in the documentation. If None, it will be the name of the package.

• version (str) – Project/package version.

Raises:

• ValueError – Raised if the project already exists.

• ValueError – Raised if the package does not exist.

• SphinxError – Raised if an error occured during the creation.

generate_project_files(sub_dir='')

Generate the project files (*.rst files).

Parameters:

sub_dir (str) – A sub-directory of the project_source_dir where the module documentation will be generated in.

Raises:

• ValueError – Raised if the project and/or package does not exist.

• SphinxError – Raised if an error occured during the generation.

package_exists()

Return True if the package exists.

Return type:

bool

project_exists()

Return True if the Sphinx project exists.

Return type:

bool

quickstart(author, project_name=None, version='1')

A wrapper for creating, generating, and building documentation.

Parameters:

• author (str) – Author of the project.

• project_name (str) – Name of the project.

• version (str) – Version of the project.

validate_package()

Validate the package.

Raises:

ValueError – Raised if the package does not exist.

validate_project()

Validate the project.

Raises:

ValueError – Raised if the project does not exist.

validate_project_and_package()

Validate the project and package.

Raises:

ValueError – Raised if the project or package does not exist.

property package_dir

Return the package directory as a Path object.

Return type:

Path

property project_build_dir

Return the project build directory.

Return type:

Path

property project_dir

Return the project directory.

Return type:

Path

property project_source_dir

Return the project source directory.

Return type:

Path