发布于 2015-09-16 15:34:59 | 329 次阅读 | 评论: 0 | 来源: 网络整理
Since many projects will need special features in their documentation, Sphinx is designed to be extensible on several levels.
This is what you can do in an extension: First, you can add new builders to support new output formats or actions on the parsed documents. Then, it is possible to register custom reStructuredText roles and directives, extending the markup. And finally, there are so-called “hook points” at strategic places throughout the build process, where an extension can register a hook and run specialized code.
An extension is simply a Python module. When an extension is loaded, Sphinx imports this module and executes its setup() function, which in turn notifies Sphinx of everything the extension offers – see the extension tutorial for examples.
The configuration file itself can be treated as an extension if it contains a setup() function. All other extensions to load must be listed in the :confval:`extensions` configuration value.
These extensions are built in and can be activated by respective entries in the :confval:`extensions` configuration value:
sphinx.ext.autodoc – Include documentation from docstrings
sphinx.ext.autosummary – Generate autodoc summaries
sphinx.ext.doctest – Test snippets in the documentationsphinx.ext.intersphinx – Link to other projects’ documentationsphinx.ext.graphviz – Add Graphviz graphssphinx.ext.inheritance_diagram – Include inheritance diagramssphinx.ext.refcounting – Keep track of reference counting behaviorsphinx.ext.ifconfig – Include content based on configurationsphinx.ext.coverage – Collect doc coverage statssphinx.ext.todo – Support for todo itemssphinx.ext.extlinks – Markup to shorten external linkssphinx.ext.viewcode – Add links to highlighted source codesphinx.ext.oldcmarkup – Compatibility extension for old C markupYou can find several extensions contributed by users in the Sphinx Contrib repository. It is open for anyone who wants to maintain an extension publicly; just send a short message asking for write permissions.
There are also several extensions hosted elsewhere. The Wiki at BitBucket maintains a list of those.
If you write an extension that you think others will find useful or you think should be included as a part of Sphinx, please write to the project mailing list (join here).
Extensions local to a project should be put within the project’s directory structure. Set Python’s module search path, sys.path, accordingly so that Sphinx can find them. E.g., if your extension foo.py lies in the exts subdirectory of the project root, put into conf.py:
import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']
You can also install extensions anywhere else on sys.path, e.g. in the site-packages directory.