Get More reST: Adding Files

Installing Markdown parser

First, you will need to install the Markdown parser with the following command:

pipenv install --dev recommonmark

Note: It’s already installed here.

Then, modify the conf.py by adding recommonmark to the list of extensions. For example, you would change:

extensions = ['sphinx.ext.autodoc']

to

extensions = ['sphinx.ext.autodoc','recommonmark']

Also, the source suffix must be changed to include Markdown with the line:

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

Adding some additional files

Now add the additional files you want into the toctree within the index.rst file in the docs/source directory. Sphinx is limited to only include files that are in the source directory. For example, if we want to include a README.md file, that is, in the root of the repository, we must either move it, copy it, or create a symbolic link. The last option is the best: it makes the same file simultaneously accessible from two different locations in the directory structure. It is only possible in Unix-based operating systems like Mac and Linux. To do this, we can move it to the source directory and use the ln command.

ln -s ../../README.md

Be sure to add the README.md symbolic link to the Git repository so that git can track it. Symbolic link tracking doesn’t work on Windows platforms, so we will need to move or copy the file. We can now add the file to the toctree directive in the index.rst file. It could look something like the following, with thanks.rst and changelog.md being the two other files we create.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   README.rst
   changelog.md
   thanks.rst

The result is a list of links within the HTML documentation that allow us to go between the various pages. The higher-level structure will be shown on each page in a sidebar on the left.