mmf.sphinx.ext.apigen¶
| ApiDocWriter(package_name[, rst_extension, ...]) | My version that actually imports the modules. |
| MonkeypatchAutodoc | This fixes some behaviour in sphinx.ext.autodoc that causes our generated documentation to fail. |
| isinterface(obj) | |
| isclass(obj) | |
| generate_api(app) | This function actually generates the API documentation. |
| setup(app) | The guts of the extension. |
Inheritance diagram for mmf.sphinx.ext.apigen:
This extension automatically generates API documentation. To use it:
Include ‘mmf.sphinx.ext.apigen’ in the extensions list in your conf.py file.
Note
This extension must be installed before the :ext:`sphinx.ext.autosummary` extension.
Set the configuration option apigen_packages to a list of packages for which you would like to generate. These must be importable.
Specify apigen_outdir as the output directory. The default is in the doctreedir/_generated/api but it is probably better if you set this explicitly.
Include the index_* files in a toctree directive:
.. toctree:: :maxdepth: 2 :glob: _build/_generated/api/index_*
This will generate the full API.
Document your modules. The following module attributes affect what is added to the generated documentation:
- __all__
This list is a standard python feature. It defines which symbols are imported with from mod import * for example. If defined, then only attributes included here will be documented. If this is not defined, then the list of objects to document will be extracted from the module __dict__.
- __apigen__
Dictionary with the following keys: ‘include’
List of objects to include in documentation. These can be strings or a compiled re.RegexObject object.
- ‘exclude’
List of objects to exclude from documentation. These can be strings or a compiled re.RegexObject object.
- `‘nowarn’
This boolean flag can be set to True to suppress warnings about the module not defining __all__. Typically, if __all__ is not defined, then the user will be warned that all imported objects will also be documented. This is usually not desired because, for example, imported modules might be very large and should be documented on their own. However, it can be tedious to maintain __all__, so if a module as changing content, then it might be desirable to deduced the contents from __dict__.
Note
In this case, you should probably be careful to delete or exclude any imports you do not want documented.
The following config values control the generation of the API documentation.
- apigen_packages¶
This should be a list of importable package names. The API documentation will be generated for these.
- apigen_outdir¶
The documentation will be placed in this directory (default is the $(doctreedir)/_generated/api directory.)
- apigen_package_skip_patterns¶
None or sequence of {strings, regexps}. Sequence of strings giving URIs of packages to be excluded. Operates on the package path, starting at (including) the first dot in the package path, after package_name - so, if package_name is sphinx, then sphinx.util will result in .util being passed for searching by these regexps. If is None, gives default. Default is: ['\.tests$']
- apigen_module_skip_patterns¶
None or sequence. Sequence of strings giving URIs of modules to be excluded Operates on the module name including preceding URI path, back to the first dot after package_name. For example sphinx.util.console results in the string to search of .util.console If is None, gives default. Default is: ['\.setup$', '\._']
- apigen_label¶
If True, then section labels “Modules”, “Classes”, “Functions” etc. will be generated, otherwise, the type can be inferred from the name: Modules will have a ”.” prepended, interfaces start with “I”, classes have nothing, and functions end in “()”.
- apigen_autosummary¶
If True, then an :ext:`sphinx.ext.autosummary` table will be generated at the start of each module summarizing the contents.
- apigen_headings¶
If True, then each function, class, interface, and module will appear as a heading so that the structure appears in the table of contents. This is somewhat redundant though.
- apigen_inherited_members¶
If True, then inherited members of each class will be included, otherwise, the user must follow the links to the base class. Default is False.
Todo
We presently exclude extension modules.
To include extension modules, first identify them as valid in the _uri2path method, then handle them in the _parse_module script.
We get functions and classes by parsing the text of .py files. Alternatively we could import the modules for discovery, and we’d have to do that for extension modules. This would involve changing the _parse_module method to work via import and introspection, and might involve changing discover_modules (which determines which files are modules, and therefore which module URIs will be passed to _parse_module).
Note
This is a modified version of a script originally shipped with NIPY which in tern was a modified version of a script originally shipped with the PyMVPA project. PyMVPA is an MIT-licensed project.
Warning
We monkey-patch autodoc.py a bit to get things working. See MonkeypatchAutodoc.
- class mmf.sphinx.ext.apigen.ApiDocWriter(package_name, rst_extension='.rst', package_skip_patterns=None, module_skip_patterns=None, labels=False, autosummary=True, inherited_members=False, headings=False)[source]¶
Bases: mmf.sphinx.ext.apigen._ApiDocWriter
My version that actually imports the modules.
Methods
discover_modules() Return module sequence discovered from self.package_name generate_api_doc(uri) Make autodoc documentation template string for a module get_package_name() set_package_name(package_name) Set package_name write_api_docs(outdir) Generate API reST files. write_if_changed(filename, contents) Write the contents to file if they have changed, otherwise write_index(outdir[, froot, relative_to]) Make a reST API index file from written files write_modules_api(modules, outdir) Initialize package for parsing
Parameters : package_name : string
Name of the top-level package. package_name must be the name of an importable package
rst_extension : string, optional
Extension for reST files, default ‘.rst’
package_skip_patterns : None or sequence of {strings, regexps}
Sequence of strings giving URIs of packages to be excluded Operates on the package path, starting at (including) the first dot in the package path, after package_name - so, if package_name is sphinx, then sphinx.util will result in .util being passed for searching by these regexps. If is None, gives default. Default is: [‘.tests$’]
module_skip_patterns : None or sequence
Sequence of strings giving URIs of modules to be excluded Operates on the module name including preceding URI path, back to the first dot after package_name. For example sphinx.util.console results in the string to search of .util.console If is None, gives default. Default is: [‘.setup$’, ‘._’]
labels : bool
If True, then section labels “Modules”, “Classes”, “Functions” etc. will be generated, otherwise, the type can be inferred from the name: Modules will have a ”.” prepended, interfaces start with “I”, classes have nothing, and functions end in “()”.
autosummary : bool
If True, then an :ext:`sphinx.ext.autosummary` table will be generated at the start of each module summarizing the contents.
inherited_members : bool
If True, then inherited members of each class will be included, otherwise, the user must follow the links to the base class. Default is False.
headings : bool
If True, then each function, class, interface, and module will appear as a heading so that the structure appears in the table of contents. This is somewhat redundant though.
Methods
discover_modules() Return module sequence discovered from self.package_name generate_api_doc(uri) Make autodoc documentation template string for a module get_package_name() set_package_name(package_name) Set package_name write_api_docs(outdir) Generate API reST files. write_if_changed(filename, contents) Write the contents to file if they have changed, otherwise write_index(outdir[, froot, relative_to]) Make a reST API index file from written files write_modules_api(modules, outdir) - __init__(package_name, rst_extension='.rst', package_skip_patterns=None, module_skip_patterns=None, labels=False, autosummary=True, inherited_members=False, headings=False)¶
Initialize package for parsing
Parameters : package_name : string
Name of the top-level package. package_name must be the name of an importable package
rst_extension : string, optional
Extension for reST files, default ‘.rst’
package_skip_patterns : None or sequence of {strings, regexps}
Sequence of strings giving URIs of packages to be excluded Operates on the package path, starting at (including) the first dot in the package path, after package_name - so, if package_name is sphinx, then sphinx.util will result in .util being passed for searching by these regexps. If is None, gives default. Default is: [‘.tests$’]
module_skip_patterns : None or sequence
Sequence of strings giving URIs of modules to be excluded Operates on the module name including preceding URI path, back to the first dot after package_name. For example sphinx.util.console results in the string to search of .util.console If is None, gives default. Default is: [‘.setup$’, ‘._’]
labels : bool
If True, then section labels “Modules”, “Classes”, “Functions” etc. will be generated, otherwise, the type can be inferred from the name: Modules will have a ”.” prepended, interfaces start with “I”, classes have nothing, and functions end in “()”.
autosummary : bool
If True, then an :ext:`sphinx.ext.autosummary` table will be generated at the start of each module summarizing the contents.
inherited_members : bool
If True, then inherited members of each class will be included, otherwise, the user must follow the links to the base class. Default is False.
headings : bool
If True, then each function, class, interface, and module will appear as a heading so that the structure appears in the table of contents. This is somewhat redundant though.
- class mmf.sphinx.ext.apigen.MonkeypatchAutodoc[source]¶
This fixes some behaviour in sphinx.ext.autodoc that causes our generated documentation to fail. In particular:
Some sphinx.ext.autodoc.Documenter.can_document_member() instances treat parent as a sphinx.ext.autodoc.Documenter whereas sphinx.ext.autosummary typically passes objects (such as modules). Thus, functions in a module attempt to be documented by sphinx.ext.autodoc.MethodDocumenter rather than sphinx.ext.autodoc.FunctionDocumenter. This is fixed by MyDataDocumenter and MyMethodDocumenter
sphinx.ext.autodoc.ModuleDocumenter cannot document submodules for some reason (changed in sphinx revision 02f38aa14aaf). I need this functionality, so I restore it in MyModuleDocumenter.
Note
As far as generating documentation, this is not needed if the sub-module is in __all__. However, if it is not included, then in some other places I have had problems. For example, module documentation will sometimes be passed to numpydoc with as an attribute or class, so numpydoc tries to parse it and complains about Unknown sections (object docstrings must have a specific set of sections, but module docstrings can have anything).
Methods
MyAttributeDocumenter MyDataDocumenter MyMethodDocumenter MyModuleDocumenter - class MyAttributeDocumenter(directive, name, indent=u'')[source]¶
Bases: sphinx.ext.autodoc.AttributeDocumenter
Methods
add_content add_directive_header add_line check_module document_members filter_members format_args format_name format_signature generate get_doc get_object_members get_real_modname import_object parse_name process_doc resolve_name
- class MonkeypatchAutodoc.MyDataDocumenter(directive, name, indent=u'')[source]¶
Bases: sphinx.ext.autodoc.DataDocumenter
Methods
add_content add_directive_header add_line check_module document_members filter_members format_args format_name format_signature generate get_doc get_object_members get_real_modname import_object parse_name process_doc resolve_name
- class MonkeypatchAutodoc.MyMethodDocumenter(directive, name, indent=u'')[source]¶
Bases: sphinx.ext.autodoc.MethodDocumenter
Methods
add_content add_directive_header add_line check_module document_members filter_members format_args format_name format_signature generate get_doc get_object_members get_real_modname import_object parse_name process_doc resolve_name
- class MonkeypatchAutodoc.MyModuleDocumenter(directive, name, indent=u'')[source]¶
Bases: sphinx.ext.autodoc.ModuleDocumenter
Methods
add_content add_directive_header add_line check_module document_members filter_members format_args format_name format_signature generate get_doc get_object_members get_real_modname import_object parse_name process_doc resolve_name