Sphinx and ReadTheDocs Tutorial
An important part of any software project is documenting your code so that others understand how to use it. Sphinx is a tool that takes the documentation you have written and generates beautiful and readable web pages that show your documentation. Any time your project is rebuilt, Sphinx automatically will update your documentation if you change anything. Once you have generated your Sphinx docs, it is easy to host them online through ReadTheDocs.org, which integrates with Sphinx.
This tutorial will guide you through the process of generating Sphinx documentation and uploading it to ReadTheDocs.org. It assumes you already have a Python project and that you understand basic conventions for file structures in Python projects. If you wish to familiarize yourself a little more with Python packaging, check out this tutorial.
If you are documenting your code using widely accepted docstring conventions, Sphinx can automatically generate stylized and readable web documentation. Sphinx supports a wide variety of docstring conventions that we won't cover here, but below is an example of a function documented properly using sphinx-compatible docstrings:
Before we can use Sphinx, we have to install it. From the terminal, enter the command pip install sphinx. Now, we need to make a directory within our project where we will store all our documentation and Sphinx-generated files will be stored. In root folder of our project, create a folder named "docs" with mkdir docs. cd into the folder.
Run the command sphinx-quickstart which helps create everything we need to get started. When we run sphinx-quickstart, a series of questions will be asked. y means yes, n means no, and whatever is in the [] brackets is the default if you choose neither and just press enter.
Choose the default option for all except “autodoc: automatically insert docstrings from modules”. Enter y for that, since we want Sphinx to create our documentation automatically.
We do not need a windows command file, so type n for "Create windows command file?".
Here is what it should look like when you have finished running sphinx-quickstart:
Sphinx will now have generated a number of files in our docs/ folder, but let’s start with what was generated in conf.py. There are lots of things you can edit here, including some of the things you entered in during sphinx-quickstart.
Near the top we are going to un-comment a few lines that will let Sphinx know where the root of our project is. If the “docs” folder is located at the root of your project (like was recommended above), you can simply put ‘../’ as the path.
The next item to consider is the theme for the HTML files you will be generating. The default is “alabaster”, and while the theme is mostly a cosmetic choice, I would recommend themes besides alabaster. Feel free to look up all the different possible themes for Sphinx. The one that looks best in my opinion and matches the theme of ReadTheDocs.org is the readthedocs theme for Sphinx. To use it, first enter the command pip install sphinx_rtd_theme in the terminal. Then in conf.py, change the theme from alabaster to sphinx_rtd_theme.
Now comes the time for Sphinx to generate pages that will be used to create our HTML web pages. First, we need to decide what files of code we want to generate documentation for. Remember, even though you should document code for your own benefit, most of it is probably not intended for or is even accessible by the end user. Once we have decided which files to create documentation for, it is time to create all the .rst files that Sphinx will base its HTML documentation files off of. RST files are a simple type of markdown file that aren’t too difficult to edit or learn about. If you are interested in learning more about how to edit RST files, check out this tutorial. For now though, we don’t need to worry about it.
Here is the general format for the command to generate our RST files:
sphinx-apidoc -o output_directory source_directory [files_to_ignore]
output_directory is wherever we want to put the generated RST files. In this example, it is fine to simply keep them in the docs/ folder with everything else, so for output_directory we can put ./ (which means current directory).
source_directory is the root of where your source code is actually located. If you are currently in the docs/ directory, that might simply be up one level at ../. Or, if you have all of your code in a subdirectory named source then for source_directory we can put ../source. For this tutorial, we will assume our code is located in the ../source directory.
After we specify output_directory and source_directory, we can specify what files or directories we want to ignore and not create documentation for. For example, if I had a folder named secret_code and a file named dont_look.py under ../source/ that I didn’t want to generate documentation for, I would simply list them after I list output_directory and source_directory. I can list as many as I want, each separated by spaces.
Putting it all together, the command will look like this:
sphinx-apidoc -o ./ ../source ../source/secret_code ../source/dont_look.py
If you would like to do a dry run of the sphinx-apidoc command above to make sure that it is only creating pages for the files you want, you can add the -n flag to the command and it will tell you what would be created, but doesn’t actually do anything. This is useful for making sure you have the syntax right. That command would look like this:
sphinx-apidoc -n -o ./ ../source ../source/secret_code ../source/dont_look.py
Once you feel confident you will generate documentation for the files you want, go ahead and run the command without the -n flag. Now you have all the RST files you need to make your HTML pages! One of the pages that was created is called index.rst, which will act as a home page for your documentation. Again, feel free to edit these as you like or just leave them as they are.
The last step is to actually make the HTML pages. To do so, enter the command make html into the terminal inside your docs folder. If everything works, you will see a message that indicates where the HTML pages are located. Feel free to open them up in a web browser to see what they look like!
Add and push all your new files to GitHub and we are ready to host your documentation!
Your documentation is nice and looks good, but it isn’t any use if it isn’t published for other people to see and reference. ReadTheDocs.org is a great, free platform to host your documentation that integrates easily with Sphinx.
Go to ReadTheDocs.org (NOT readthedocs.com) and create a new account. I recommend signing in with GitHub to streamline the whole process.
Once an account is made, select “My Projects” from the dropdown menu in the top right corner:
Select “Import a Project”
Find your project from GitHub and import it. Now your documentation should build!
There is one final step that may need to happen in order for your documentation to build correctly. In order for ReadTheDocs to build your documentation, it actually has to build your entire project first. So, we have to tell it what dependencies the project has so it can be built properly.
Click on the "Admin" button, and go to "Advanced Settings":
If you are building a typical python project, and you have a setup.py file for installing your project, you can simply check the box that says “Install your project inside a virtualenv using setup.py install”. If you don’t have a setup.py file, you need to create a pip requirements file in your repository and provide the path to it.
Making a pip requirements file, called requirements.txt, is very easy. Just list the dependencies you would need to install with pip, one on each line. If my project had dependencies on pandas and numpy, the contents of requirements.txt would read:
pandas numpy
You can also specify versions if you need to, just like you would when installing something via pip. Make sure you save changes at the bottom of the Advanced Settings page.
Congratulations! You have just published your documentation on ReadTheDocs. You can click on the green "View Docs" button to see what is actually being hosted. If you followed the tutorial, you will see that it's pretty simplistic. You can click on "Index" to view documentation for different functions. Now you have the option to go back and customize the RST files however you want to suit the needs of your project.