Documenting your product can be a critical factor in product success and user satisfaction. Your documentation should be structured, readable and searchable in order to make the best impact and to provide the best results for your customers. In this article I want to show how easy it is to create a very nice documentation site, using Sphinx tool and markdown language.
From Sphinx website: 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 IMHO more widely known and used.
Sphinx also has a few built in themes, and many more available externally (one google search away…). We will use sphinx-rtd-theme, which seem to be used by many open source projects out there, and feels familiar.
Installation
Sphinx is a python package, so create a new python project and install the following packages:
sphinx — sphinx package
sphinx-rtd-theme — a theme package
recommonmark — package for markdown support
sphinx-markdown-tables — package for markdown tables support
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 initialize 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 all the content (md files) 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
The resulting documentation is static HTML so it is very easy to self host it, or use one of the popular services for hosting.
