An Introduction To Sphinx

What is Sphinx? Well, in a nutshell, Sphinx is a Python documentation generator, but in reality, it is so much more. Sphinx has the rather impressive capability of converting reStructuredText and Markdown documents into HTML files, PDF’s and much more.

This means with Sphinx, you have the capability to create entire static sites out of Markdown documents, which is pretty nifty! Sphinx gives you the capability to create custom themes whilst also providing an abundance of prebuilt options and configurations.

How do I get started Sphinx, well a good place to start is the installation guide and getting started guide on the official site. You will need to ensure you have Python installed along with a package manager such as pip or brew.

The first thing I did to get to grips with Sphinx was creating a quick start project using the following command.

sphinx-quickstart

This will give you a template to work from, it generates all relevant files and provides a default theme.

The File Structure

A useful place to start when learning Sphinx is to acquire an understanding of the file structure and what roles each file has.

The config.py file