How to install read the docs in Windows Environment

Tutorial on how to successfully install Python with Sphinx in Windows. Step by step guide.

What is Sphinx?

Sphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML. For our use case you can think of it as a program that takes in plain text files in reStructuredText format, and outputs HTML.

Why do you need Sphinx?

So as a user of Sphinx, your main job will be writing these text files. This means that you should be minimally familiar with reStructuredText as a language. It’s similar to Markdown in a lot of ways. It’s a lot more powerful than Markdown, but with that power comes increased complexity. Just know that some of the awkward syntax allows you to do more interesting things further down the line. In particular, it is extensible: it has a formal way of adding markup directives that allow more sophisticated parsing. For example, Sphinx includes directives to relate documentation of modules, classes and methods to the corresponding code.

Why this guide?

Currently there are dozens of tutorials and guides of how to install Sphinx in Windows environment. Unfortunately they all are incomplete and they are all missing/skipping some important steps. This guide will help you get Sphinx up and running in no time.

Instructions to setup read the docs in Windows

This is a complete guide of how to install Sphinx in Windows. Follow this 6. easy steps to successfully install sphinx in windows:

1. Install Python for Windows

If you don’t have Python for Windows, please go to https://www.python.org/ and via download section download and install Python.

2. Setup Environmental Variables

Open “Environmental Variables” option within Windows

Right click on My Computer icon
Properties
Advanced
Environmental Variables
Click ‘New’
Variable name = Path
Variable value = Full path to Python main folder & Python scripts folder

In example below , I have Python installed on D:\Python and Scripts folder is inside that folder . So full Variable value in my example is “D:\Python ; D:\Python\Scripts “

3. Open elevated Command Prompt

Press Start, type Command Prompt
Right click on command prompt , click run as administrator
If you've setup correctly Environmental Variables , you should be able to run python

4. Install Sphinx

Run this command from Command prompt

Pip install sphinx

If everything works it should say that Sphinx has been successfully installed.

*note that in my example below, I already have Sphinx installed

5. Start creating HTML files

Open any text editor, notepad, word, etc. and start typing your to be html file
Save it as .rts file in D:\Python\Scripts\Docs folder *

*Full path of the python installation may be different than yours

Below are rules for restructuredtext . http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

6. Easily convert .rst files to html read the docs format

After you’ve finished editing .rst documents and now you wish to convert them to html format for read the docs
Open again Command prompt in admin mode
go to your python\scripts folder
type make html while you are in that folder
That’s it, your .rst files are easily converted to .html

7. Open html to view results

Your html files will be in D:\python\Scripts\docs\_build\html folder (note that your python full path may be different)

Conclusion

After spending few hours searching the web for the instructions on how to setup python/sphinx on windows environment, I came to conclusion that there are bunch of incomplete guides/tutorials on how to do so. I wrote this article to help community in search for complete guide. As you’ll see, sphinx is very fast and easy tool to create Html docs.