-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Fix #1135: Make 'sphinx-apidoc' an extension
This is an alternative approach to #1135. Rather than modifying the 'build_sphinx' setuptools extension, we allow 'sphinx-apidoc' to be run as an extension. This is very similar to what we do with 'sphinx-autogen', which can be run automatically using the 'autosummary_generate' configuration option instead. We may wish to remove the 'sphinx-apidoc' binary in the future, but that's a decision for another day. Signed-off-by: Stephen Finucane <stephen@that.guru>
- Loading branch information
1 parent
f26db5b
commit 39386c2
Showing
7 changed files
with
133 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,51 @@ | ||
.. highlight:: rest | ||
|
||
:mod:`sphinx.ext.apidoc` -- Generate autodoc stub pages | ||
======================================================= | ||
|
||
.. module:: sphinx.ext.apidoc | ||
:synopsis: Generate autodoc stub pages | ||
|
||
.. versionadded:: 1.7 | ||
|
||
The functionality of this extension was previously available as part of the | ||
:program:`sphinx-apidoc` tool. This ability to run this automatically by way | ||
of a Sphinx extension was added in 1.7. | ||
|
||
This extension generates function, method and attribute stub documentation | ||
pages, similar to that generated by API doc tools like Doxygen or Javadoc. | ||
|
||
.. warning:: | ||
|
||
The apidoc extension generates source files that use | ||
:mod:`sphinx.ext.autodoc` to document all found modules. If any modules | ||
have side effects on import, these will be executed when building | ||
documentation. | ||
|
||
If you document scripts (as opposed to library modules), make sure their | ||
main routine is protected by a ``if __name__ == '__main__'`` condition. | ||
|
||
Configuration | ||
------------- | ||
|
||
The apidoc extension uses the following configuration values: | ||
|
||
.. confval:: 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. | ||
|
||
.. confval:: apidoc_output_dir | ||
|
||
The output directory. If it does not exist, it is created. This path is | ||
relative to the documentation source directory. | ||
|
||
Defaults to ``api``. | ||
|
||
.. confval:: apidoc_excluded_modules | ||
|
||
An optional list of modules to exclude. These should be paths relative to | ||
``api_module_dir``. fnmatch-style wildcarding is supported. | ||
|
||
Defaults to ``[]``. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
from os import * | ||
|
||
|
||
class Foo: | ||
def __init__(self): | ||
pass | ||
|
||
def bar(self): | ||
pass |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
# -*- coding: utf-8 -*- | ||
|
||
import os | ||
import sys | ||
|
||
sys.path.insert(0, os.path.abspath('./')) | ||
|
||
extensions = ['sphinx.ext.apidoc'] | ||
master_doc = 'index' | ||
|
||
apidoc_module_dir = '.' | ||
apidoc_excluded_modules = ['conf.py'] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
apidoc | ||
====== | ||
|
||
.. toctree:: | ||
|
||
api/modules |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters