Documenting with Sphinx tutorial: Part 2—Implementation

This is Part 2 of a four-part tutorial.

Part 2: Implementation

Watch the video or continue reading below:

In Part 1 of this tutorial, we installed and created a virtual environment and set up Sphinx which generated some base files for us to work on. In this part, we’re going to:

1. Work with the index.rst file
2. Build in HTML
3. Play around with different themes

Working with the index.rst file

The index file—located under the source folder—is the home page of your documentation. Use any text editor of your choice to open the file.

You can use vim to open the file directly on the command line. In the source folder, run
vim index.rst

This opens up the file directly in the command line.

• Press ‘i‘ to begin editing from here.
• To return back to the command line, hit Esc first to exit editing mode. Then type :wq and press Enter. (wq to save and quit, q alone will just quit).

I prefer using Sublime Text and edited the index file there.

The only requirement for the index file is there needs to be a toctree directive. This tells Sphinx the hierarchy and relations between the files in your docs.

• By default the toctree will show up in the HTML output (as a Table of Contents) but you can hide this as I’ve shown in Part 3 of this tutorial.
• You can leave it anywhere in the file either at the top or bottom. Save your work when done.

Build docs

Let’s see how the index file looks in the browser. This involves ‘building’ the documentation with the ‘builder’ in this case being HTML.

1. In the command line, go to your project folder (or whichever folder you created your virtual environment in) and activate the environment.
   source env/bin/activate
2. Go to the docs folder (or whichever folder you installed Sphinx in) and run
   make html

The html files are now in the build folder. If there were any errors when running the build, e.g. if you deleted the toctree by mistake, you will see a warning message(s) in red over here.

3. In the command line, navigate to the build and html directories and open the index.html file with any browser of your choice. Alternatively open the index.html file directly from Finder or your file explorer.

4. The file is opened in the browser.

Sphinx used the default theme set up in the conf.py (configuration) file: Alabaster.

Changing the theme in Sphinx

Sphinx comes with several built-in themes that you can view here:
https://www.sphinx-doc.org/en/master/usage/theming.html

As an example, let’s change our theme to bizstyle.

1. In the source folder, open the conf.py file using vim or another text editor.
   vim conf.py
2. Look for the line that says
   html_theme='alabaster'
3. Change alabaster to bizstyle (or any built-in theme of your choice).

4. Save the config file and return back to the command line.
5. In the docs folder (or wherever Sphinx was installed), run
make html
and open the index.html file in a browser.
6. The new theme is now displayed.

If you wish to create your own theme, this page has more details:
https://www.sphinx-doc.org/en/master/theming.html

You can also install a third-party theme such as the ReadTheDocs theme.

1. In the command line, run
   pip install sphinx_rtd_theme

2. Open the conf.py file and change as follows:

3. Run a build (make html) in the docs folder again to view your file in the ReadTheDocs theme:

Conclusion

In this section, we started to work on the home page of our documentation and looked at how to switch to different themes as well as install a third-party theme like ReadtheDocs.

In Part 3, we’re going to get into the meat of our documentation—creating new pages for our docs and writing in reStructuredText.