Read The Docs are a great way to documenting your work and I recently had to make one for my club, WnCC.

You have two options which in which you can write your documentation. Either markdown or reStructuredText. The official documentation of RTD recommends using reStructuredText so that is what we are going to do.

Install Python and Sphinx

Install Python, the version I am using white writing this documentation is 2.7.10. You can use Python3 as well, there won’t be any issues. Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. To install it via pip

pip install sphinx sphinx-autobuild

Configuring Docs

Make the directory of yours docs,

$ cd /path/to/project
$ mkdir docs

In that directory run sphinx-quickstart. This will walk you through the basics of setting up your docs. In most case you will choose the default option. Once this process is complete you will have a proper directory stucture formed. When it’s done you will have a index.rst and conf.py. All the options you select in sphinx-quickstart will appear in conf.py and you can edit them there as well.

Your directory will have a source directory and a build directory. The build directory is the one which has all the html rendered files from the .rst files you write in the source directory. To inialise the theme and have the needed templated in the build folder. The default theme is alabaster, however how I’ve used the sphinx_rtd_theme. You can install it via pip using pip install sphinx_rtd_theme and then change your theme in conf.py. Now that you have it all setup run sphinx-autobuild source build/html and go http://127.0.0.1:8000.

Writing Content

Now that you have everything setup, it’s time to fill in some content. Edit your index.rst and write

WnCC Journal
========================================

.. toctree::
   :maxdepth: 4
   :caption: Contents:

   portals/portals
   wiki/wiki
   website/website

The first line contains the heading and the other entry is toctree which stands for Table Of Content Tree. These two are compulsory entries for the index.rst file. The toc tree depicts the stucture of docs. So in the source directory make directories and some rst files so that it looks something like this

.
├── _static
├── _templates
├── conf.py
├── index.rst
├── portals
│   └── portals.rst
├── website
│   └── website.rst
└── wiki
    └── wiki.rst

Mentioning portals/portals in the toctree defines the landing page for each. Now if you save all this and go back to your page you will see:

Each of these will direct to rendered .rst mentioned in the toctree by you in index.rst.

Managing Directories

Now to have a proper tree with proper links make your docs directory look something like this.

.
├── _static
├── _templates
├── conf.py
├── index.rst
├── portals
│   ├── django.rst
│   ├── portals.rst
│   ├── server.rst
│   └── templates.rst
├── website
│   ├── hook.rst
│   ├── jekyll.rst
│   ├── server.rst
│   └── website.rst
└── wiki
    ├── backup.rst
    ├── setup.rst
    └── wiki.rst

Now modify the wiki.rst to look something like

Wiki
====

.. toctree::
   :maxdepth: 4
   :caption: Contents:

   setup
   backup

The === signifies that the text written over it is a title, only by writing === does Sphinx generate a link to it. Note that in this toctree only the .rst files in the same directory are mentioned. Go ahead and do this for the rest.