Sphinx is a document processor application that is supposed to make it easier for developers to create comprehensive documentation. Initially Sphinx was developed for compiling Python documentation and was later on released as a separate solution. Now it’s available under the BSD license.
Sphinx is especially applicable when working with some version control system to monitor all the changes. Collaborators using different systems will also benefit from plain text documentation as plain text is considered the most portable format available.
Even though Sphinx is a Python-based application and was primarily developed for creating Python language documentation, it can be viewed as language-independent tool and in sometimes, not even programmer-specific. Sphinx can be used for many purposes, including writing a book.
Sphinx Features
As we’ve mentioned Sphinx originally was Python-specific, but the latest release shows that it has excellent facilities for creating documentation of projects, developed in C/C++ as well, and it is planned to add support for other languages in the nearest future. Sphinx utilizes reStructuredText as its markup language, and many of the features listed below come from the very nature of reStructuredText and its parsing and translating suite, the Docutils.
The core features of Sphinx that should be brought out:
- Supported output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), Texinfo, PDF, epub, man (UNIX Manual Pages), plain text
- Broad cross-referencing options: semantic markup and automatic links for functions, classes, citations, glossary terms
- Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
- Automatic indices: general index as well as a language-specific module indices
- Code handling: automatic highlighting using the Pygments highlighter
- Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
Highlighting
Sphinx has code highlighting for Python by default, but it also allows definition of other programming languages like C and Ruby.
We should consider Sphinx as a documentation framework: it takes out the gruesome parts and provides automatic functionality to tackle the most common issues like title indexing and special code highlighting with appropriate syntax highlighting.
Sphinx Extensions
Since Sphinx is used in a variety of diverse projects, it cannot by itself offer the needed support, so from the start Sphinx was designed as a greatly extensible documentation tool. So, what can you do with an extension?
First of all, you can plug in a new builder to enable new output formats or actions on the parsed documents. Then, it also becomes possible to extend the markup by registering custom reStructuredText roles and directives. And lastly, Sphinx allows so-called “hook points” at specific places through the building process, where the extension is able to register that hook and execute the needed piece of code.
An extension is essentially a Python module that upon upload is imported into Sphinx and run with itssetup() function - it also informs Sphinx about all the functionality that extension provides.
Some plugins are pre-installed, like interSphinx that allows linking various Sphinx projects, other you will need to add separately.
Conclusion
This article was aimed at providing you with the introductory information on Sphinx, but there is a lot more to learn and explore. Sphinx has the ability to export documentation in different formats, but they require extra libraries and software to be installed. Some of the formats that can be generated are: PDF, epub, man (UNIX Manual Pages), and LaTeX. If the look and feel of the generated output was not to your liking, Sphinx includes many themes that can be applied to completely change how the HTML files render the documentation.
Have any questions, contact Quintagroup today.