Introduction to Sphinx

Advantages

Documentation is integral to fast development. When we revisit the project after a while, good documentation helps us quickly remember what we were doing and where we left off. Better documentation means more people are likely to use the code. This is especially true if we have good documentation on installing our project and how to use it. Also, if we’re building an open-source project, people will be more likely to contribute to it if they can see how our code works.

Documentation tool

The best documentation tool for Python is Sphinx. The first version was released in 2008 for the documentation of Python and its standard libraries. Sphinx relies on some documentation conventions and configuration decisions to extract all the documentation strings from our code and compile them into a manual. It takes the programming principle of “Don’t Repeat Yourself” and applies it to the documentation. Rather than documenting the code itself and then creating a documentation file with Sphinx, we do it once and use it twice. We can then expand on the automatically extracted parts to write introductory pages or pages on special topics. The automatically created documentation can be compiled into a website or a PDF file, among other options.