Creating documentation

This section describes how sphinx documentation can be created for your project. Typically this documentation would be generated within a code repository.

Getting started

Follow the quick-start instructions on the official sphinx documentation page During this process, it will ask Separate source and build directories (y/n). Select yes.

Example repositories

https://so-tools.readthedocs.io/

Markdown

By default, sphinx recognises RestructuredText. Markdown is an alternative, and relatively simpler plain text format for writing structured documents. Sphinx supports an unambiguous version of Markdown called CommonMark which addresses many of Markdown’s limitations.

Markdown best practices

A guide to best practices when using Markdown can be found in the following link.

Adding support for Markdown files

CommonMark can be enabled in Sphinx by including the Recommonmark extension in the Sphinx conf.py. See official sphinx documentation page for instructions on how to enable this sphinx extension.

Adding new markdown files

A new markdown file can be added to your project as described below (ensure that the Recommonmark Sphinx extension has been enabled as described in the previous section).

1. Create a new text file with the .md extension in appropriate folder within the standard sphinx docs/source folder, e.g. docs/source/my/folder/file.md.

2. This new file can be added to the main Sphinx table of contents by adding the filename to the index.rst file in the docs/source/ folder as shown below:

   ===========================
   Welcome to my documentation
   ===========================
   
   .. toctree::
      :maxdepth: 2
      :caption: Contents:
   
      my/folder/file
   

Building documentation

Building documentation from the command line

Change directory to the folder where the sphinx documentation was generated (typically /path/to/docs/) in the terminal, and run the following command:

make html

Building documentation using Pycharm

Follow the instructions in the following link. Python provides a markdown plugin that allows for dynamic previewing of markdown files as shown in the figure below: Pycharm dynamic markdown preview!

Additional features

Linking to heading sections in other markdown files

When writing documentation, it might be useful to reference headings sections in other markdown files. This can be enabled using the following instructions.

For example, to link to a section named # My subtitle in a file located in /path/to/file.md, relative to the docs/source folder.

[text for the link](/path/to/file:My%20Subtitle)

NOTE:

1. Any spaces in headings need to be replaced by %20.
2. The .md file extension should not be included in the path to the file.

restructuredText

Add ability to reference sections

See this Section