In order to configure and use Read the Docs in Windows environment you need to follow these steps:
Go to http://python.org/ and download version 2.7.x
Follow the Windows installer for Python.
Please select “Add python.exe to Path”.
Complete the installation.
Now run the Command Prompt (with Admin privileges). After command prompt window appear, type python and Enter.
If the Python installation was successful, the installed Python version is printed, and you are greeted by the prompt >>>.
Type Ctrl+Z and Enter to quit.
Otherwise, if python command was not found you must insert manually these lines in the Environment Variables Path:
- Right click on Computer > Click on Properties
- Click on Advanced system settings on the left (see picture below)
- Click on “Environment Variables”
- Select the Path System Variables and add these two lines in the path C:\Python27\;C:\Python27\Scripts;
Install the pip command
To install pip, download https://bootstrap.pypa.io/get-pip.py and save it somewhere. After download, invoke the command prompt, go to the directory with get-pip.py and run this command:
C:\> python “<folder_path>\get-pip.py”
Now pip command is installed. From there we can go to the Sphinx install.
Installing Sphinx with pip
If you finished the installation of pip, type this line in the command prompt:
C:\> pip install sphinx
After installation, type sphinx-build on the command prompt. If everything worked fine, you will get a Sphinx version number and a list of options for this command.
Defining a new project documentation
The root directory of a Sphinx collection of reStructuredText document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation.
and answer its questions. (Be sure to say yes to the “autodoc” extension.)
> Root path for the documentation [.]: <Enter>
You have two options for placing the build directory for Sphinx output. Either, you use a directory “_build” within the root path, or you separate
“source” and “build” directories within the root path.
> Separate source and build directories (y/n) [n]: y
Inside the root directory, two more directories will be created; “_templates” for custom HTML templates and “_static” for custom stylesheets and other static files. You can enter another prefix (such as “.”) to replace the underscore.
> Name prefix for templates and static dir [_]: <Enter>
The project name will occur in several places in the built documentation.
> Project name: <project_name>
> Author name: <author_name>
Sphinx has the notion of a “version” and a “release” for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don’t need this dual structure, just set both to the same value.
> Project version: 1.0
> Project release [1.0]: <Enter>
The file name suffix for source files. Commonly, this is either “.txt” or “.rst”. Only files with this suffix are considered documents.
> Source file suffix [.rst]: <Enter>
One document is special in that it is considered the top node of the “contents tree”, that is, it is the root of the hierarchical structure of the documents. Normally, this is “index”, but if your “index” document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: <Enter>
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]: y
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write “todo” entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> pngmath: include math, rendered as PNG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html’ instead of invoking sphinx-build directly.
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: y
Creating file .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file .\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
where “builder” is one of the supported builders, e.g. html, latex or linkcheck.
And now … Start the Docs 😉