Every project needs documentation, and without proper documentation, a project is unlikely to survive the test of time. That’s why we have so many tools to help us with documenting things. One such tool very widely used is sphinx.
Sphinx is a highly configurable tool, and so I will go through the basic configuration parameters that I had to deal with while setting up sphinx on my GSoC project. Please be aware that this is not a sphinx-tutorial, just a documentation of few peculiar things I came across while working with sphinx.
For a Java project, this is easily achieved using Java docstrings, and similar stuff is achievable via python triple quoted strings (docstrings).
So the first point to note is, sphinx works with
rst or ReStructured Text and expects the documentation strings to follow the same as well.
This might sound a little imposing at first, but really, rst is a nice and clean format, much better than markdown in many cases !
And you also have quite a few options to choose from in case you don’t like to document your docstrings in
Also sphinx has this
autodoc extension, which automatically crawls the desginated packages and crawls through all their docstrings and generates a beautiful documentation for our api, ready to be hosted.
The best part is that it can also be integrated tightly with our project’s
It fits in tightly, and can be invoked with
python setup.py develop.
Just for reference, setup.py can have almost any command in the docs section, so it’s definitely possible to use some other documentation generator as well !
Also, sphinx uses a
conf.py as it’s configuration file, and it has a
sphinx-quickstart that sets up most of the stuff quickly and automatically according to the answers given to questions that it asks.
Some quick reference guides that I found useful while setting up
- http://www.sphinx-doc.org/en/1.7/setuptools.html : For more ambitious people who want to explore more about
python setup.py docsscenario .
Thanks for reading !