Posted in GSoC, Python

Documenting with sphinx

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 rst.
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 setup.py.
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 sphinx for coala-antlr:

Thanks for reading !

Advertisements

Author:

Code Lover

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s