Skip to main content

A Sphinx extension for running 'sphinx-apidoc' on each build

Project description

https://travis-ci.org/sphinx-contrib/apidoc.svg?branch=master

A Sphinx extension for running sphinx-apidoc on each build.

Overview

sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools. sphinx-apidoc does not actually build documentation - rather it simply generates it. As a result, it must be run before sphinx-build. This generally results in tox.ini files like the following:

[testenv:docs]
commands =
  sphinx-apidoc -o doc/api my_code my_code/tests
  sphinx-build -W -b html doc doc/_build/html

This extension eliminates the need to keep that configuration outside Sphinx. Instead, this functionality can be enabled and configured from your documentation’s conf.py file, like so:

extensions = [
    'sphinxcontrib.apidoc',
    # ...
]
apidoc_module_dir = '../my_code'
apidoc_output_dir = 'reference'
apidoc_excluded_paths = ['tests']

Configuration

The apidoc extension uses the following configuration values:

apidoc_module_dir

The path to the module to document. This must be a path to a Python package. This path can be a path relative to the documentation source directory or an absolute path.

Required

apidoc_output_dir

The output directory. If it does not exist, it is created. This path is relative to the documentation source directory.

Optional, defaults to api.

apidoc_excluded_paths

An optional list of modules to exclude. These should be paths relative to apidoc_module_dir. fnmatch-style wildcarding is supported.

Optional, defaults to [].

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinxcontrib-apidoc, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size sphinxcontrib_apidoc-0.1.0-py2.py3-none-any.whl (10.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size sphinxcontrib-apidoc-0.1.0.tar.gz (7.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page