How to make a nice-looking documentation

Since I’m doing more and more programs and courses about coding, I see a need for a better way to make nice-looking documentation.

When I started using GitHub for hosting my code I transitioned from a simple text file, such as a README.txt file, to a more shiny markdown one, or README.md.

This already allowed me to embed pictures, separate paragraphs, and highlight code. At this link, you can find a lot of nice and interesting things about GitHub markdown syntax, which is just a regular text with some interpreted characters.

Then I tried different solutions like using using GitHub Pages and Jekyll (see this RNAseq course done in 2019, and this documentation of a tool published in 2019) and bookdown, an R-based markdown language that produces HTML files. You can see an example of a Nextflow course here.

Since a few years ago is becoming trendy to store the documentation into a dedicated hosting resource called Read the Docs. The theme is really nice and professional and the hosting allows you to have different versions of the manual for each version of the tool.

So I decided to transition again, but I choose to use the open-source tool python-based Sphinx on which Read the Docs is based, to have the documentation inside the same repository.

Example of the documentation made with Sphinx and hosted by Read The Docs

I tried different solutions and here I’ll show you the easiest way, based on the good work from Sphinx Pages. In brief, you will set up a GitHub Action that will trigger the generation of the documentation, without installing anything.

GitHub will run on its own servers a docker image containing what is needed for building the documentation starting from your markdown files and it will place it in a new branch called gh-pages.

Data and code availability :)

All the files shown in the following example are in this repository (https://github.com/lucacozzuto/test_doc).

So, let’s start

Let’s create a new repository called test_doc and let’s add a number of files needed by Sphinx:

• requirements.txt
• conf.py
• The markdown files: index.rst, one.rst, and two.rst

Requirements.txt contains a list of optional plugins needed by sphinx. For a basic case, you just need the theme (sphinx_rtd_theme).

Conf.py is more complex and allows you to modify the behavior of the building. In this example from Sphinx Pages you have a selection of the most common options, here the full list.

A part that you might want to change is at the beginning:

# -- Project# -- Project information -------------------------------
project = u'Test made by Luca Cozzuto using Sphinx Page GitHub Action'
copyright = u'2019, Sean Zheng'
author = u'Sean Zheng'

This will be put on the final website as well.

Files ending with .rst contain the markdown that has to be interpreted. The first one of our example contains just:

.. _home-page:

*******************
This is an example of documentation
*******************

This is done automatically thanks to:

`Shinx-pages <https://github.com/seanzhengw/sphinx-pages>`_

Contents:

.. toctree::
   :maxdepth: 1

   one
   two

Basically, we make a table of contents using the Sphinx directive “toctree”, in which we list the pages we want to be displayed. We also add the maxdepth option may for indicating the depth of the tree.

Other directives are shown as examples in one.rst and two.rst, such as

.. image:: test.jpeg
  :width: 400

that will insert an image or:

.. code-block:: python
# This program prints Hello, world!
print('Hello, world!')

that will highlight the python code.

Once everything is ready we can set up the GitHub Actions for the automatic building just creating a new file at .github/workflows/github-actions.yml with the following content:

on: [push]
jobs:
  build:
    name: Something
    runs-on: ubuntu-latest
    steps:
    - uses: seanzhengw/sphinx-pages@master
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        create_readme: true

This will tell GitHub to make a new branch (gh-pages) and to run the content from seanzhengw/sphinx-pages@master.

Finally we can publish our documentation as GitHub Pages, by going into GitHub setting:

And then Pages. You need just to activate it and to select the gh-pages branch. You will have the documentation at https://USERNAME.github.io/test_doc.

The result of our example is here: https://lucacozzuto.github.io/test_doc

In case you want to separate the code from the documentation, you can move the *.srt files to a folder named docs for instance, and then modify this part of the conf.py to point to the docs folder

# The master toctree
#document.master_doc = 'index'
document.master_doc = 'docs/index'

Your documentation will be at now at:

https://lucacozzuto.github.io/test_doc/docs/