How to deploy a sphinx styled documentation

In this tutorial guide I will show you how to create a documentation for your project using the Sphinx style.

Sphinx is a documentation generator written and used by the Python community and environments.

Sphinx uses the reStrcuturedText markup language by default and can also be tweaked to using markdown.md as a third party package

In this tutorial guide I’ll show you how to

1. Install sphinx on your project
2. Setup Sphinx on your project
3. Run Sphinx with some basic commands
4. Install a different theme
5. Deploy your documentation on reathedocs

First create a project on GitHub and clone it on your local machine or alternatively clone this blank project

cd into the directory of the repo you just cloned with
cd demo-sphinx-tutorial

Create a virtual environment with
python3 -m venv venv if you’re on a linux server like I am or python -m venv venv on a windows

Activate your virtual environment with
source venv/bin/activate on a linux server venv\Scripts\activate on a windows and open your project in your choice editor.

Install Sphinx
pip install sphinx

Setup Sphinx
sphinx-quickstart docs

Now what this is going to do is to run you through a bunch of questions, whenever you want to accept the default value just go ahead and press enter

Separate source and build directories (y/n) [n]: 
press y

The project name will occur in several places in the built documentation.
> Project name: demo-sphinx-tutorial
> Author name(s): Tim Osahenru
> Project release []: 1.0

> Project language [en]: 
press enter

Run Sphinx
cd into source folder and make a directory called images with mkdir images where our images will be stored
your file tree should look like this

open the index.rst file this is where the magic takes place, you want to leave this section.

the toctree tells sphinx the hierarchical order of your file, you can either push to the bottom of the page of leave it ontop DO NOT DELETE THIS

next I’m going to copy and paste some dummy data into the index.rst file

now we build our documentation with this commands sphinx-build -b html docs/source/ docs/build/html

To view your built work open the build folder and load index.html on your browser

NB:
whenever you make a change inside the index.rst
file always make sure you build with 
sphinx-build -b html docs/source/ docs/build/html

Install theme
To pick a theme visit for this tutorial this theme was used

install the theme with
pip install sphinx-rtd-theme

locate this session in your conf.py file and change html_theme = 'alabaster' to html_theme = 'sphinx_rtd_theme' and build again with sphinx-build -b html docs/source/ docs/build/html

PART II

Deploying to readthedocs
cd into you docs folder and create a requirements file with pip freeze > requirements.txt for readthedocs to know the dependencies used on this project

Perform these git commands to push to GitHub where we will be deploying our project from

git status
git add .
Git commit -m ‘first commit’
git push

Create an account on readthedocs navigate to your profile image button and click the drop down menu
click on My Projects > Import a Project select the project you wish to deploy and click on Build Project

Once the build is successful you should get an indication and have a project like this.
Congratulations!