Read time: 7.1 minutes (714 words)

Step 2: Basic Sphinx Setup

All projects should be documented. I am not talking about sprinkling code with comments, that is not documentation. A well documented project has material aimed at the users of the product, and the developers of the project. The users obviously need to know how to use the product, and developers need to know how and why it was put together the way it is presented. Those developers may need to fix bugs in the project, or add new features. The developers may not even have been part of the original team that put the project together.

Sadly, many projects fail to address these documentation needs.

The Python world has settled on a nice documentation tool called Sphinx. This tool processes simple text documents written in a simple markup language called reStructuredText, that is quite readable even without processing. The Sphinx tool can generate many different types of output, but we will focus only on two: HTML for display on the web, and LaTeX which can be used to generate PDF output.

Installing Sphinx

Since Sphinx is a Python tool, installation is accomplished using the standard pip tool. This can be run from a command line, but since I am going to develop this project using PyCharm we will install it inside the IDE:

Start up PyCharm and open the project. Then select PyCharm ‣ Preferences Next select Project: … ‣ Python Interpreter. Click on the gear icon at the right side of the selection window. This window will create a Python virtual environent` where all project dependencies will be manages separated from any other |PY| projects you might be working on. The default **venv* directory will be initialized with a Python interpreter and all packages needed for the project will be installed inside this directory as well.

Click OK when you are satisfied with the entries. Once the venv directory has been set up make sure that the Python interpreter points to venv/bin/python.

Next, create a new requirements.txt file in the top level project directory. Open this file and add this line:

sphinx

Once that line is in place, select Install requirement and the IDE will install Sphinx.

Note

All future project requirements will be listed in this file and installed the same way.

Set up a Sphinx Project

We will be publishing the documentation for this project using GitHub Pages, a free hosting service to GitHub users. All HTML web pages stored in a docs directory in the project will be made visible after we do a little setup work on GitHub.

Start off by creating two directories: docs and rst. We will create our documentation source files under the rst directory and generate web pages in the docs directory. Both of these directories can be created using the File ‣ New ‣ Directory menu.

Run Sphinx Quickstart

Select Tools ‣ Run Sphinx Quickstart. Change the path shown so it points to the rst directory, then click OK.

In the console panel you will be asked a few questions. Just press :kbd``Enter` except for these entries:

  • Author - Add your name

  • Project Release - Most projects start off with release 0.1.0

This step creates several files in the rst directory.

You should check the conf.py file to make sure your setting are correct.

Create a Documentation Run Configuration

Select Run ‣ Edit Configurations. Click on Add new configuration ‣ Sphinx Task. Make sure the Input field points to the rst directory and the Output field points to the docs directory. When you are ready, click on OK.

Test Build

Now you can test the documentation setup by selecting Run ‣ Sphinx Task. With any luck, your first documentation build will appear in the docs folder.

Push to GitHub

We can now push the changes to the project to GitHub. Unfortunately, doing everything needed for this step inside PyCharm proved impossible. PyCharm had already added both its special .idea directory and the venv directory, both of which I did not want posted on GitHub. The fix was to open up a command line and do these commands:

$ git reset .idea
$ git reset venv
$ git status
$ git add .
$ git status
$ git commit -m "Initial Sphinx setup"
$ git push

At this point, navigate to your project on GitHub and select Settings. Scroll down to the Github Pages area. Make sure the branch is main and the docs folder is selected. Once these are set click on Save. You can now navigate to the public pages:

https://rblack42.github.io/math-magik

Adding a Custom Theme

By default, Sphinx uses a pretty bland theme. I looked at several themes on the Internet and discovered that I looked to one Sphinx uses on its own project pages! So, I copied that theme into this project The additions are now in the project directory and changes to the conf.py file are in place as well.

Todo

Add documentation on customizing this theme.