Spotlight on Sphinx: Python Docs For Everyone

If you’ve ever looked at the Python documentation, you’ve seen Sphinx in action.

Sphinx is an open-source project that allows people to automatically generate static websites for Python documentation. Besides code-heavy documentation, it can also be used as a static site generator.

What is Sphinx?

Sphinx is a Python project that takes in reStructuredText and outputs static web pages. It is most commonly used to host documentation. With Sphinx installed, you can write comments in your code similar to how you would with JavaDoc, and it will pull in all those comments to provide a big picture of your functions and classes. This can be extremely helpful as a programming reference, and since it pulls directly from the code, you don’t have to worry about it getting out of sync.

Who’s using it?

Sphinx was originally created to host the official Python documentation, but it’s only grown from there. Many popular libraries use Sphinx to host their documentation, and it’s become something of an industry standard among Python developers.

In addition, the popular documentation site Read The Docs makes this process even easier by allowing developers to host and update their Sphinx docs by connecting the repository and building the docs just like you would code. This “docs-as-code” approach helps ensure maximum compatibility between the code and the documentation, and helps mitigate documentation debt.

Here are some notable companies or libraries using Sphinx to host their websites or documentation:

• CakePHP (Sphinx is not just for Python!)
• Numpy
• SageMath
• Pip (Python’s package manager)
• OpenCV

It doesn’t stop at just documentation. Some people have written their personal sites, courses, or even whole books using Sphinx:

• Benoit Boissinot
• Theoretical Physics Reference Book
• The Wine Cellar Book

How can Sphinx help me?

Now that you know about all the great things Sphinx can do, I bet you’re wondering how you can use it in your work. Sphinx is adaptable enough to work for many use cases, but it really shines at documenting code, Python code in particular.

If you’re writing Python software as part of your job and having trouble maintaining the docs (or God forbid, you don’t have any docs!), Sphinx is definitely worth a try. It’s free, open source, and there are a variety of resources and tutorials out there to help you customize it to your needs.

Sphinx is great when you have structured information. In this way, Sphinx might not be such a great choice if you’re trying to host your latest novel, but it is a good idea for technical manuals with a complex table of contents that people will need to navigate. Another great feature of Sphinx is that it comes with search built-in, so you don’t have to worry about pulling in another package to do the heavy lifting for you.

Set up your first Sphinx site

Ready to get started? Let’s go through the basics of installing and setting up your first Sphinx site.

You can install Sphinx from PyPI (Python Package Index) by running this command:

$ pip install Sphinx

Once Sphinx is installed, run sphinx-quickstart from your project folder to initialize a project there:

$ sphinx-quickstart

• 1. Sphinx-quickstart will go through and ask you a bunch of questions. This sets up some initial configuration values, but you can always go back and change them later. For most projects the defaults will suffice. Be sure to enter your project’s name and the project author when prompted.
  2. If you’re wanting to generate docs from your Python code, be sure to enable the autodoc extension (disabled by default).
  3. When sphinx-quickstart is finished running, you should have several new files and folders used to configure and manage your site. If you need to change any of the configuration values in the future, you can do that in conf.py.
  4. The Makefile is what allows us to build the documentation and package it into HTML for the web. To build the example skeleton project, run:

$ make html

The output files should be in _build/html. Navigate there now:

$ cd _build/html

The home page for our site is index.html. Open that file in a web browser to see the example project:

$ open index.html

You should see the basic layout of your new Sphinx site.

Congratulations! You have Sphinx up and running.

For next steps on how to add posts and customize Sphinx, I recommend Brandon’s Sphinx Tutorial (PDF). It’s both informative and easy to follow.

Now that you know about Sphinx, go out there and Write The Docs!