Writing Documentation on Read the Docs - Part 2

In the previous blog - Writing Documentation on Read the Docs - Part 1 we installed sphinx and configured it to use Markdown and sphinx-rtd-theme. In this blog, we will find out how to write docs and add contents to it.

Writing the docs

Make sure you have setup your project to use Markdown  and have configured conf.py to use sphinx-rtd-theme, if not then please have a look at Part 1 of this blog.

We will be using Atom IDE to write our documentation, though you can use any other Text Editor like Notepad, or Sublime Text.

Create a new page and add it to your project :

Add a new file in your docs/ directory and give it an extension *.md , in the example shown below, I have created a file named Writing-Documentation.md .

Add new file in docs/ folder and give it extension *.md

To make this page appear in the Contents section of your project, add an entry in the index.rst as shown in the figure above. Note that the name should be exactly the same as your filename without the extension '.md' . Take note of type-case sensitivity.  

Basic Formatting

You can use basic formatting options like add Headers, Lists, add images and Links in Markdown.
Github has a list of common formatting options available in their Markdown-cheatsheet.

Markdown Cheatsheet - Img Courtesy guides.github.com

Adding images and gifs

All images and gifs needs to be placed inside the docs/_static directory of your project.
Once the files have been place in the _static directory, we can link the images in the documentation using the following syntax - 


Here I have added a close photograph of a modern Intel CPU. 

Adding image in your documentation

Image of a Modern-day CPU

Adding Permalinks to Headers

Headers are automatically numbered by sphinx, this makes it easy to divide pages into sections and sub-sections.

The topmost header (h1) corresponds to # in Markdown, to define sub-sections you can just add more headers using double hashes ## and further sub-sections using ### and so on.

To add permalink to your sub-sections, you need to use the markup for Link and in the parenthesis write the name of the heading in the following way :

So if you've a header 'Introduction to Read the Docs' in your page then to add permalink to it, you need to write

- [Introduction to Read the Docs](#introduction-to-read-the-docs)

NOTE : The text inside the parenthesis must always be in small case and words separated by hypen (-). The text must always begin with # even when adding link to header (h2, h3 or any other).

Building your project as HTML Document

To build your project as HTML Document run the following command from docs/ directory of your project - 

$ make html

All HTML files have been generated in the docs/_build/html directory of your project.

You can view your generated documentation by opening index.html  in the browser of your choice.

The image on the left shows how your docs/_build/html directory looks like after building your project.

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.