Create Sphinx based documentation with Markdown

Introduction

Our latest project documentation was created with Sphinx. 

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.

Sphinx is natively using reStructuredText format, but we will use markdown, as it is more widely known and used.

Installation

Sphinx is a python package, so create a new python project and install the following packages:

• Sphinx - sphinx package
• recommonmark - package for markdown support
• sphinx-markdown-tables - package for markdown tables support
• sphinx-rtd-theme - a theme package

Initialisation

Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. To initialise a new project just run this:

sphinx-quickstart

Then answer a few questions (choose to have source and build separate) to complete the setup.

Project structure

Quick start command will generate a few folders and files.

• source directory - is where sll the content should be stored.
• conf py file - this is the file where all the project configurations are stored
• index.rst - this is the main documentation page. It is the only file that we will keep in rst format.
• make.bat - called to generate output

Configuration

All configuration is done in conf.py file. The file contains comments explaining each section. We will configure the following:

Support for markdown format (in addition to native rst support):

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown'
}

Packages we need to support markdown:

extensions = [
    'recommonmark',
    'sphinx_markdown_tables'
]

Theme and theme settings:

html_theme = 'sphinx_rtd_theme'

html_theme_options = {
    'logo_only': True,
    'display_version': True,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': True,
    # Toc options
    'collapse_navigation': False,
    'sticky_navigation': False,
    'navigation_depth': 3,
    'includehidden': True,
    'titles_only': False
}
html_title = "My amazing documentation"
html_logo = "path/to/logo.png"
html_favicon = "path/to/favicon.ico"

Index setup

Index.rst file is the master document. The main function of the master document is to serve as a welcome page, and to contain the root of the “table of contents tree” (or toctree). By default it contains a single toctree entry, but in order to have nice sidebar sections, we use multiple toctrees.

.. toctree::
   :maxdepth: 1
   :hidden:
   :caption: Section 1:

   docs/MyDoc1.md
   docs/MyDoc1.md

.. toctree::
   :maxdepth: 2
   :caption: Section 2:

   docs/MyDoc3.md
   docs/MyDoc4.md
   docs/MyDoc5.md

• Documents path specified as relative to source directory
• :maxdepth: - how many sub-section levels to show (relevant only for the welcome page, not the sidebar)
• :hidden: - in case we want to hide the section from the main page. (in our plugin configuration we stated that we want to use hidden section in sidebar: ‘includehidden’:True)

Markdown pages

All the documentation content is stored in .md files in markdown standard format (same format that is used for wikis on github/gitlab/etc) The only format requirement that is needed for Sphinx in order to generate a consistent menu bar is to have # Title in the file. It will be used by the toctree. 

Generating HTML

When all the changes are completed on the markdown files, or after each change, run the following command to generate html output:

make html

It will output the html website to /build/html directory. Console output is very useful for identifying any issues with content (for example it will alert you if a document exists that is not included in toctree).

You can now view your documentation in your favorite browser.

Result Example

Hope this helps someone.