Writing Documentation on Read the Docs - Part 1

Read the Docs is an Open-Source Project which makes hosting Documentation for the Open-Source Community easy and hassle-free. Read the Docs supports formatting documentation in reStructuredText and Markdown. It is possible to use reStructuredText and Markdown together in the same sphinx project.
The User manual for GraphSpace is hosted using Read the Docs, it uses Markdown and a custom theme called sphinx-rtd-theme.
In this tutorial, we will find out how to build docs using Markdown and the sphinx-rtd-theme.

GraphSpace uses the classic sphinx-rtd-theme

Installing Sphinx and other dependencies 

Make sure you have the following prerequisites  installed in your system - 

• Python 2.7 or Higher
• Pip

*pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4 downloaded from python.org 

Now, we are ready to setup Sphinx. Sphinx is a tool that makes it easy to create beautiful documentation. Assuming you have Python already, install Sphinx:

$ pip install sphinx sphinx-autobuild

Install recommonmark to use Markdown with Sphinx.

$ pip install recommonmark

Install sphinx-rtd-theme, we will be adding this theme later in the configuration file.

$ pip install sphinx-rtd-theme

Create a directory inside your project to hold your docs:

$ cd /path/to/project
$ mkdir docs

Next, navigate to the docs directory just created and run sphinx-quickstart :

$ cd docs
$ sphinx-quickstart

Configuring sphinx 

The quick start will walk you through the basic configurations, you can accept the default values or change any specific config you want. When it is done, a default project structure will be created along with these 2 files - index.rst and conf.py.

In order enable Markdown support in our local build, we need to add the following lines in conf.py 
and comment any source_suffix in the config file -

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

Next we need to add the sphinx-rtd-theme we installed earlier to our project, to do this add the following line in the conf.py file - 

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Now your project has been successfully setup to use Markdown  and sphinx-rtd-theme.

Check part 2 of this blog to find out how to add content and images to your project.