Documenting with Sphinx Tutorial: Intro & Overview

This is an introduction to the four-part tutorial that follows on how to document your project using the Sphinx python module. In this introduction, I want to expand on what this means conceptually, and describe the steps involved in documenting and using Sphinx.

Watch the video or continue reading below:

Who is this tutorial for?

This is a beginner-friendly tutorial and guide. I’m assuming you’re a little uncomfortable with using the command line, not quite sure how Github works, open source seems like a strange world to you—basically I’m assuming you’re like me. If your skills are a little more advanced, feel free to use this as a reference.

Why use Sphinx for documentation?

Sphinx is a free open source project written in Python and was indeed, originally created for Python documentation. It has since become a tool that creates elegant documentation for software projects supporting a range of languages. Basically, it takes a bunch of text files written in a language called reStructuredText and renders it (mainly) as HTML. ReStructuredText is a powerful markup language designed specifically for technical documentation.

One of Sphinx’s most attractive features is its extensions—these are simply Python modules—that let you do cool things with your documentation like add Google maps, embed YouTube videos, insert diagrams and so on. Programmers in particular seem to love Sphinx because it actually makes them want to document their code—apparently writing documentation is as exciting for them as getting a root canal (weirdos).

Sphinx workflow

This is how I picture it in my head:

Practically speaking though, I haven’t had to deal with Docutils1 The Docutils library was already installed at some point in my computer. so let’s sneakily remove that and add a Github step instead:

Let’s translate the above diagram into what you would actually need to do as a technical writer from start to finish, and in what order.

Steps involved in documenting in Sphinx

1. Creating and cloning a Github repository

Skip the paragraph below if you’re already familiar with Github.

Quick recap: Git is the software, Github is the hosting platform for git projects. When you want to host a project on Github, you first need to create a repository2Like a giant folder that contains everything related to your project. You can choose to create the repo with a .md file called Readme (a markdown file) which is where others first go to find out what your project is all about. You can keep adding folders and files to this repository by using git commands (on the command line).
To make changes to someone else’s repo, you first have to fork it3Make a copy on your own account, clone it4Get the copy onto to your local system. and then configure git so that your local clone and fork are always in sync with the original repo. The term upstream refers to the original repository, and origin refers to your fork (copy) of that repository.

The very first thing you need to do if you don’t have one, is create a Github account (step 5 below provides more detail on why we’re doing this).

What’s involved:

1. Creating a repository for your project. If you’re creating documentation for someone else’s repository, then you have to fork their repo.
2. Cloning the repository to your local drive.

This will generate an empty folder to your drive with your repository name. If you’re cloning someone else’s repo, the folder probably won’t be empty.

2. Setting up a virtual environment

You could try installing Sphinx right away, but your command line will probably yell at you, and that’s because you need to set up a virtual environment first before you can install Sphinx. So let’s start there.

What is a virtual environment?

No, it’s not some kind of alternate reality—it helps rather to think of it as a sandbox where your Python project will live.

You can create many sandboxes to manage different projects so that they live in isolation from one another, and can have their own dependencies5Sometimes when you install a program (say, X), it requires other programs (library Y) to work. These other programs are called dependencies, so Y is X’s dependency. kept separate from one another. The advice is to set up a virtual environment every time you work on a Python-based project. For tech writing purposes, this explanation suffices but if you want a more detailed explanation, you can find one here.

What’s involved:

1. Installing the virtual environment on the command line.
2. Activating it every time you want to work on your project.

3. Setting up Sphinx

Now that you have your virtual environment set up, the next step is to install Sphinx. Sphinx is the tool that will actually render the text files you write into HTML pages.

What’s involved:

1. Installing Sphinx on the command line.
2. Doing an initial setup.

This generates an index.rst file (among others) that you can start writing on.

4. Writing ReStructuredText files

This is where you’ll spend most of your time as a technical writer. Sphinx requires files written in a markup language called reStructuredText (.rst files). This is an easy-to-read, what-you-see-is-what-you-get plain text markup syntax and file format.

As mentioned above, the first file you’ll see is an index.rst file. This will be the home or welcome page of your future documentation, and also the page where you will lay out the hierarchy of all future pages (i.e., how the Table of Contents will look).

You will keep creating new .rst files for each web page you want your final documentation to have. As you write, you can keep running a ‘build’ in Sphinx to see how your work looks in the browser.

What’s involved:

1. Using a text editor of your choice to open and create new .rst files.
2. Learning how to write in reStructuredText.6Initially, writing may be a bit slow as you learn the basic markups for the most common tech writing needs (inserting an image, marking something bold etc.), but it gets a lot quicker after that!

5. Pushing docs to Github

Github is a web-based hosting platform where open source projects can live. The reason we’re pushing our files to Github is because our final resting place for the docs—ReadtheDocs—pulls the docs in from a Github repository. If your docs aren’t living there, ReadtheDocs is not interested.

What’s involved:

1. Using the command line and git commands: Pushing all your files and images to the repository created in step 1.

6. Creating a ReadtheDocs account

ReadtheDocs is a documentation hosting platform that uses Sphinx to automatically build documentation as it gets pushed to Github. Of course, you can use other themes apart from ReadtheDocs if you wanted. From a technical writing perspective, this step requires the least work.

What’s involved:

1. Create a Readthedocs account.
2. Connect your Github repo to it.

Readthedocs does the rest!

Structure of the Tutorial

Following the above discussion on the steps involved in using Sphinx, I’ve designed the tutorial as follows:

Part 1: Setting up will cover Steps 1, 2 and 3
Part 2: Implementation will describe how to begin working on the index file and change the theme for your documentation.
Part 3: Writing will cover Step 4 above—writing and formatting in reStructuredText.
Part 4: Hosting will cover Steps 5 and 6.

Conclusion

This post aimed to look at the bigger picture and explain everything you need to do—and why—in order to document your project using Sphinx. The first few steps, i.e. cloning the repository, installing both a virtual environment and Sphinx, and setting up ReadtheDocs are one-time actions that you won’t have to think about again. Writing will take up most of your time (as it should). Pushing your docs to Github will become a matter of repeating the same steps over again.

In Part 1, we’re going to fire up the command line and get over our fears right into it.