|
| 1 | +--- |
| 2 | +title: "Set Up Sphinx with Python" |
| 3 | +image: |
| 4 | + path: /images/learn/sphinx-docs-page.png |
| 5 | + thumbnail: /images/learn/python-logo400x200.png |
| 6 | + caption: "Screenshot from Read the Docs theme" |
| 7 | +--- |
| 8 | + |
| 9 | +Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from [ReStructured](http://docutils.sourceforge.net/rst.html) text files. |
| 10 | + |
| 11 | +In case you need both versions, this tutorial walks through both on a Mac. Refer to the [Downloads on the Python site](https://www.python.org/downloads/windows/) for Windows. |
| 12 | + |
| 13 | +#### Installing Python 2.7.x on Mac |
| 14 | + |
| 15 | +1. Open a terminal and use `brew` to install Python 2.7.x. |
| 16 | + |
| 17 | + ``` |
| 18 | + brew install python@2 |
| 19 | + ``` |
| 20 | +
|
| 21 | +#### Installing Python 3.x |
| 22 | +
|
| 23 | +You also want the latest version of Python 3 available. |
| 24 | +
|
| 25 | +1. Open a terminal and use brew to install the latest Python 3.x (currently 3.7). |
| 26 | +
|
| 27 | + ``` |
| 28 | + brew install python |
| 29 | + ``` |
| 30 | +
|
| 31 | +#### Verifying Python 2 and Python 3 |
| 32 | +
|
| 33 | +1. Open a terminal. |
| 34 | +1. Verify that Python 2 is correctly installed. |
| 35 | +
|
| 36 | + ``` |
| 37 | + python2.7 -V |
| 38 | + ``` |
| 39 | + Expected output for August 2018: |
| 40 | + ``` |
| 41 | + Python 2.7.15 |
| 42 | + ``` |
| 43 | +1. Verify that Python 3 is correctly installed. |
| 44 | +
|
| 45 | + ``` |
| 46 | + python3.7 -V |
| 47 | + ``` |
| 48 | + Expected output for August 2018: |
| 49 | + ``` |
| 50 | + Python 3.7.0 |
| 51 | + ``` |
| 52 | +
|
| 53 | +1. Check the version set as the default version, the version of Python that is executed when you simply enter `python`. The default version of Python remains a Python 2.7 version. |
| 54 | +
|
| 55 | + ``` |
| 56 | + python -V |
| 57 | + ``` |
| 58 | + Expected output for August 2018: |
| 59 | + ``` |
| 60 | + Python 2.7.15 |
| 61 | + ``` |
| 62 | +## Set Up Virtual Environment |
| 63 | +
|
| 64 | +Let's ensure that you know how to create Python Virtual Environments for each version of Python. These [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html) provide a method of creating isolated "environments" where you can work with specific versions of Python along with independent sets of libraries and dependencies. |
| 65 | +
|
| 66 | +Most people use Virtual Environments because it's a recommended practice when working in Python to ensure a known starting point or state. |
| 67 | +
|
| 68 | +**Python 3** |
| 69 | +
|
| 70 | +1. First create a Python 3 virtual environment using the `venv` module included with Python 3. Notice the example uses `python3.7` to be clear which version of Python you want. |
| 71 | +
|
| 72 | + ``` |
| 73 | + python3.6 -m venv py3-sphinx |
| 74 | + ``` |
| 75 | +
|
| 76 | +1. Now "activate" the environment. Look for the name of the virtual environment enclosed in parenthesis after activation. |
| 77 | +
|
| 78 | + ``` |
| 79 | + source py3-sphinx/bin/activate |
| 80 | + ``` |
| 81 | +
|
| 82 | + ``` |
| 83 | + # Expected Output |
| 84 | + (py3-sphinx) $ |
| 85 | + ``` |
| 86 | +
|
| 87 | +1. Now verify that `python` is now linked to Python 3. |
| 88 | +
|
| 89 | + ``` |
| 90 | + (py3-sphinx) $ python -V |
| 91 | + ``` |
| 92 | +
|
| 93 | + ``` |
| 94 | + (py3-sphinx) $ Python 3.7.0 |
| 95 | + ``` |
| 96 | +
|
| 97 | +## Install Sphinx in the Virtual Environment |
| 98 | +
|
| 99 | +1. With the virtual environment activated, install Sphinx. |
| 100 | +
|
| 101 | + ``` |
| 102 | + (py3-sphinx) $ pip install sphinx |
| 103 | + ``` |
| 104 | +
|
| 105 | +1. To verify that sphinx is installed, run the `sphinx-build` command with the `--help` parameter. |
| 106 | +
|
| 107 | + ``` |
| 108 | + (py3-sphinx) $ sphinx-build --help |
| 109 | + ``` |
| 110 | +
|
| 111 | +## Create a Basic Sphinx Project |
| 112 | +
|
| 113 | +You can also get familiar with [ReStructured text](http://docutils.sourceforge.net/docs/user/rst/quickstart.html), a plain text markup syntax system that you use to write content in Sphinx documentation. Sphinx can also accept [Markdown](https://commonmark.org/help/) files. |
| 114 | +
|
| 115 | +1. Create a new directory for your project: |
| 116 | + ``` |
| 117 | + (py3-sphinx) $ mkdir do-docs-as-code |
| 118 | + ``` |
| 119 | +1. With the virtual environment still activated, run `sphinx-quickstart`, which creates a starting project for a Sphinx documentation project. |
| 120 | + ``` |
| 121 | + $ sphinx-quickstart |
| 122 | + ``` |
| 123 | +1. Answer all the questions from the prompts. |
| 124 | + You can choose enter to pick all the defaults and get a working project in the current directory (`.`). |
| 125 | +
|
| 126 | + Some notes for the context of this tutorial: |
| 127 | + * You can either use a directory named `_build` within the root path, or have separate `source` and `build` directories, which is the default. |
| 128 | + * 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. |
| 129 | +1. Once you have the basics answered, the script creates the necessary files and you can edit those to your liking. |
| 130 | +1. Create a couple of `.rst` files and add skeleton information for starters. |
| 131 | + ``` |
| 132 | + $ touch source/prerequisites.rst |
| 133 | + $ touch source/about.rst |
| 134 | + ``` |
| 135 | +1. Edit those new `.rst` files in your favorite text editor. |
| 136 | +1. Now, you can build the docs to see the changes locally: |
| 137 | + ``` |
| 138 | + $ make html |
| 139 | + ``` |
| 140 | +1. 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. |
| 141 | +1. Edit the `source/index.rst` file to include links to the additional pages. Here is an example: |
| 142 | + ``` |
| 143 | + .. toctree:: |
| 144 | + :maxdepth: 2 |
| 145 | + :caption: Contents: |
| 146 | + |
| 147 | + about.rst |
| 148 | + prerequisites.rst |
| 149 | + ``` |
| 150 | +1. Build again to see these changes locally: |
| 151 | + ``` |
| 152 | + $ make html |
| 153 | + ``` |
| 154 | +1. In your browser, refresh the `build/html/index.html` page to see the new Contents with two entries linked. |
| 155 | +1. Make sure you commit your changes to the Git repository by following the steps in [Working with content in GitHub repositories](https://docslikecode.com/learn/04-add-content-workflow/). |
| 156 | +
|
| 157 | +## Additional resources |
| 158 | +
|
| 159 | +[Sphinx Python Documentation Generator](http://www.sphinx-doc.org/en/stable/) |
| 160 | +[ReStructured text documentation](http://docutils.sourceforge.net/rst.html) |
0 commit comments