Wizardlab-docs¶

Wizardlab-docs is a base project for developing static documentation pages with Docker and Sphinx.

After cloning this repo, issue a docker compose up -d, and navigate to http://locahost:5000 in a web browser.

What you are viewing are html files Sphinx built as configured by build/docs/conf.py from the source files placed under wiki/.

Docker does all the heavy lifting though configuration we set in compose.yaml.

compose.yaml leverages the Dockerfile and DockerHub to build two containers:

wizardlab-doc-sphinx-1 generates the html files
wizardlab-doc-httpd-1 hosts them using apache2

The generated html can be examined under html/

Screenshot of creating documentation pages with wizardlab-docs

Resources¶

Learn about .rst: Sphinx’s reStructuredText Primer

Learn about .md: Writing on Github: Basic formatting syntax

Configuring Sphinx¶

Configuring Sphinx is a matter of adjusting a single file conf.py. This file normally lives under the docs/source/ directory, which is where the source files for your documentation would go.

In wizardlab-docs, I stash a golden-copy of conf.py in the build/docs/ folder, and I copy it over to the container’s /doc/source/ just prior to zapping the container with a command make html.

After building the html, I clean up the copied conf.py prior to mounting the html onto the httpd container.

To view how we accomplish this shuffling of files, see compose.yaml

Editing conf.py¶

The conf.py file that you need to edit lives under build/docs/conf.py

Project Information¶

sphinx-doc/usage/configuration/project-information

The Project Information section configures properties that add attribution to your project:

 # -- Project information -----------------------------------
 html_title = 'Wizardlab Docs'
 project = 'wizardlab-docs'
 copyright = '2023, The Wizard'
 author = 'Wizard Lab'
 release = '2023'

Edit the strings as needed. These settings will effect the footer and the Title of your documentation pages.

General Configuration¶

The general configuration section allows you to define extensions for Sphinx like myst_parser which allows you to build html from .md files.

templates_path effects how themes are staged
exclude_patterns allows you to instruct the engine to ignore source files. For example, you could use a _draft_*.rst exclude pattern to indicate that files that begin with _draft should be excluded from the toctree.
source_suffix provides a mapping between file extensions and documentation parsers.

sphinx-doc/usage/configuration/general-configuration

 # -- General configuration ---------------------------------
 
 extensions = ['myst_parser']
 
 templates_path = ['_templates']
 exclude_patterns = []
 source_suffix = {
     '.rst': 'restructuredtext',
     '.txt': 'markdown',
     '.md': 'markdown',
 }

NOTE: In order for a plugin to function, will will need to ensure it’s python package is being installed in our Dockerfile. See in build/Dockerfile where we install myst_parser.

Options for HTML output¶

The HTML output options are where you set themes, and define static paths.

html_theme is where you set the theme for your static pages. alabaster is the default theme, but I have already installed an additional theme furo via the Dockerfile
Static paths are important because they are files that get copied over to Sphinx’ build/html directory.

sphinx-doc/usage/configuration/options-for-html-output

 # -- Options for HTML output -------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

 html_theme = 'alabaster'
 html_static_path = ['_static']