Documenting with Sphinx Tutorial: Part 1—Setting up

Contents

This is part 1 of a four-part tutorial.

Part 1: Setting up

Watch the video or continue reading below:

In the Introduction to this tutorial, we went over what’s involved with documenting in Sphinx. In this part, we’re going to carry out the first three steps:

  1. Creating and cloning a Github repository
  2. Installing a virtual environment
  3. Installing Sphinx

Creating and cloning a Github repository

This step will generate a project folder on the local drive so that we can proceed with installing a virtual environment and Sphinx.

The instructions below assume you’re getting the docs on to your own repository. If you’re working on someone else’s repository, follow this link to fork and clone the repository and keep your fork synced as well.

  1. Create a Github account and a new repository that will hold your docs.
  2. Make a local clone of this repository. In the repository you just created, click the button to copy the repo’s URL.
Copy the repo URL

2. (contd.) In the command line, navigate to where you want the repository folder to be, and run
git clone and then paste the URL you just copied. So it should look like this:
git clone https://github.com/youraccountname/repo.git

Clone the repo

Installing a virtual environment

  1. Open your command line app (I’m using Terminal in Mac) and make sure you have Python and pip1 already installed. If you’re using Mac or Linux, Python is most likely already installed. You can check by running
    python --version
    pip --version
    in the command line.
Check for Python and pip installations

Windows users can install Python from here. If pip is not installed for you, this site might help.

2. Install virtualenv/venv: The module for installing a virtual environment is virtualenv or venv for Python 3. Run
pip install virtualenv

If you’re using Python version 3.3 or newer, you can skip this step. The preferred module for installing a virtual environment in this case is venv which will already be included in the standard library.

3. Create a virtual environment: Navigate to the folder that was created when you cloned the repository:
cd repositoryfolder

Now run
python2 -m virtualenv env

  • Replace python2 with whatever version of Python you have—my version is 2.7 (see image below).
  • Remember to replace virtualenv with venv if you are using Python 3.
  • You can replace env with any name you want—this is the name of your virtual environment. I named mine ‘jublerenv‘.
Create a new virtual environment

If this ran successfully, you will notice a new folder within your project folder. In my case, a virtual environment named ‘jublerenv‘ was created in my project directory.

5. Activate the virtual environment: Any time you want to work on your project, you should activate the virtual environment by running
source env/bin/activate
replacing env with your virtual environment name. If this is successful, you will now see (env) at the start of the terminal line.

Activate the virtual environment

Whenever you want to deactivate and get out of your virtual environment, just run deactivate in the command line, and you will get out.

Installing Sphinx

  1. To keep things organized, we’ll create a new directory called docs within our project/repository folder (that currently only has our virtual environment folder) and install Sphinx in there. After creating a new directory, navigate to it in the command line.
    mkdir docs
    cd docs
New directory for Sphinx installation

2. With your virtual environment activated, run
pip install sphinx

3. Then run
sphinx-quickstart

You’ll be asked a bunch of questions now. To accept the default value (within square brackets), press Enter.

Sphinx quickstart questions

You can answer the questions as per your own project’s requirements. I’ve listed my answers in case you’re not sure how to proceed:

Separate source and build directories: y (if your documentation is likely to be large, it’s better to say yes here)
Name prefix for templates and static dir: You can leave as is and just press Enter (or change the prefix for the two mentioned directories if you want).
Project name: Jubler (insert your own project name here)
Author name: (insert your name here)
Project release/version: 1.0 (modify as necessary)
Project language [en]: Press Enter to accept the default English
Source file suffix [.rst]: Press Enter to accept the default value (reStructuredText). (If you wanted to, you can change this to .txt for a text file, but this tutorial is going to cover how to write in .rst, so you’re good!)
Name of your master document: Press enter to accept the default value. Sphinx is going to build all the documentation against the master document—so if you’d rather give it another name like ‘main’, you can change it here.
Do you want to use the epub builder? Say no here (or enter).
autodoc: automatically insert docstrings from modules: y (I answered yes here on advice from other documenters)

For the next few options (doctest: through to githubpages:), I kept pressing Enter (or saying no) until I got to
Create Makefile? Say yes here.

Sphinx quickstart – contd.

Create Windows command file? If you’re a Windows user, type y here, otherwise n.

This should end the quickstart. If you look under the docs folder, you should now see the new files generated by Sphinx:

Conclusion

We’re done with installing, now comes the fun part! In Part 2, we’re going to work on the index.rst file and play around with themes.