Set Up Sphinx with Python

Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version, and Python 2 is an unsupported Python version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from ReStructured text files.

In case you need both versions, refer to the Downloads on the Python site.

Prerequisites

MacOS or a Linux-based environment in which to install Python.
Homebrew installed on MacOS. Get installation instructions from https://brew.sh/.

Installing Python 3.x

You want the latest version of Python 3 available.

Open a terminal and use brew to install the latest Python 3.x (currently 3.7).
```
 brew install python
```

Verifying the Python installation

Open a terminal.
Verify that Python 3 is correctly installed.
```
 python -V
```
Expected output for February 2020:
```
 Python 3.7.6
```

Set Up Virtual Environment

Let’s ensure that you know how to create Python Virtual Environments for each version of Python. These Python Virtual Environments provide a method of creating isolated “environments” where you can work with specific versions of Python along with independent sets of libraries and dependencies.

Most people use Virtual Environments because it’s a recommended practice when working in Python to ensure a known starting point or state.

Python 3

First create a Python 3 virtual environment using the venv module included with Python 3.
```
 python -m venv py3-sphinx
```
Now “activate” the environment. Look for the name of the virtual environment enclosed in parenthesis after activation.
```
 source py3-sphinx/bin/activate
```
```
 # Expected Output
 (py3-sphinx) $
```

Now verify that python is now linked to Python 3.

 (py3-sphinx) $ python -V

 (py3-sphinx) $ Python 3.7.6

Install Sphinx in the Virtual Environment

With the virtual environment activated, install Sphinx.
```
(py3-sphinx) $ pip install sphinx
```
To verify that Sphinx is installed, run the sphinx-build command with the --help parameter.
```
(py3-sphinx) $ sphinx-build --help
```

Create a Basic Sphinx Project

You can also get familiar with ReStructured text, a plain text markup syntax system that you use to write content in Sphinx documentation. Sphinx can also accept Markdown files.

Create a new directory for your project:
```
  (py3-sphinx) $ mkdir do-docs-as-code
```
With the virtual environment still activated, run sphinx-quickstart, which creates a starting project for a Sphinx documentation project.
```
  $ sphinx-quickstart
```
Answer all the questions from the prompts. You can choose enter to pick all the defaults and get a working project in the current directory (.).
Some notes for the context of this tutorial:
- If you create a working directory in your home directory, such as ~/src/, then you can use a git clone command in the src directory every time. For this tutorial, you can create a directory for your project, such as ~/src/project-name-here. This directory becomes your root path.
- You can either use a directory named _build within the root path, or have separate source and build directories, which is the default. To see an example directory structure with a source directory, refer to this justwriteclick/rockthedocs-demo repo on GitHub.
- When answering the questions, note that you can choose “githubpages set to yes” to create a .nojekyll file to publish the document on GitHub pages. In our case, though, our example builds to Read the Docs, so you can use the defaults throughout.
Once you have the basics answered, the script creates the necessary files and you can edit those to your liking.
Create a couple of .rst files and add skeleton information for starters.
```
  $ touch source/prerequisites.rst
  $ touch source/about.rst
```
Edit those new .rst files in your favorite text editor.
Now, you can build the docs to see the changes locally. Run this command in the directory with the conf.py file:
```
  $ make html
```
In your browser, open the build/html/index.html file to take a look at your Sphinx site locally. You can also look at build/html/prerequisites.html and build/html/about.html though they won’t be linked to the main page until you add them as a link or in a table of contents entry.

Edit the source/index.rst file to include links to the additional pages. Here is an example:

 .. toctree::
    :maxdepth: 2
    :caption: Contents:

    about.rst
    prerequisites.rst

Build again to see these changes locally:
```
  $ make html
```
In your browser, refresh the build/html/index.html page to see the new Contents with two entries linked.
Make sure you commit your changes to the Git repository by following the steps in Working with content in GitHub repositories.

What’s next

Evaluating options

Additional references

Enter your email for free lessons plus a review checklist in a neat PDF file.