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.
