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
- 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
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)
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.