Sunday, August 18, 2013

Sphinx extension

Sphinx is a tool to provide a special feature for the documentation of a python project. It can used to test snippets in the documentation, to link to another project's documentation, to add links to highlighted source code, to generate autodoc summaries etc. These can be achieved by some of the inbuilt extensions of the sphinx. Sphinx also provide a facility of third party extension in which a user can write an extension for some specific purpose and can upload the extension in sphinx repository.

Understanding the working of sphinx project
Sphinx project is built in several phases.
In phase0, source files are searched from the source directory and initialization of extension takes place. In phase 1, parsing of the source file takes place leading to the formation of doctree(tree formation by the use of docutils). Separate nodes are created for the directives defined in the extension. In phase 2, the doctree is checked for the formation of proper nodes with proper tagname and classes. In phase 3, the temporary nodes created in phase 1 due to improper data are converted in to nodes which can be converted into output using the meta data obtained in phase 2. In phase 4, output is obtained in desired output format.

Steps in designing of sphinx extension
Basically sphinx extension consists of four main components: Directives, Treenodes, Config files and Event handlers.Each extension consists of a setup function which registers all of these components.
Treenodes can be defined by extending the docutil classes defined in docutils.node . These are the nodes of the doctree formed during step 1 of building of sphinx project. Directives can be derived from docutils.parsers.rst.Directives or sphinx.util.compat.Directives . Config files can be used to decide the behavior extension. Finally the event handler does the main function of the extension. There are a lot of phinx APIs which can be used while writing an extension. Those can be found from http://sphinx-doc.org/ext/appapi.html

No comments:

Post a Comment