MkDocs & Docstrings

Warning

Unfortunately, MkDocs seem to be a stale project since August 2024, meaning that it can not be recommended right now (May 2026) as every day tool to document your projects. Alternativeto mentions a lot of possible alternatives. I think that I would prefer Sphinx, however, I have not decided on it.

This tab describes the usage of mkdocs within Workflow Tutor. To create an initial documentation, start with mkdocs new . within the root of your project folder.

This will create a mkdocs.yml within that folder, and a subdir docs with an index.md. Running mkdocs serve in the project folder (containing mkdocs.yml) leads to a page shown under http://localhost:8000.

Every Day Commands

  • mkdocs new . - Create a new project in the current directory
  • mkdocs serve - Start the (live-reloading) docs server, to be started in the place containing mkdocs.yml
  • mkdocs build -d pages - Build the documentation site
  • mkdocs -h - Print the help message and exit
  • mkdocs build -h - Print help message of build and exit.

Hint

As discussed here, live-reloading needs the switch --livereload since click 8.3.0, so the full command for reloading reads mkdocs serve --livereload.

Documentation Layout

This is a small overview of the documentation layout used in Workflow Tutor.

mkdocs.yml      # The MkDocs configuration file
docs/
    index.md    # The documentation homepage
    ...         # Other markdown pages, images and other files
pages/          # The static help pages

Hints & Tricks

  • Stuff like the disclaimer on the main page are called admonitions, and must be activated separately within mkdocs.yml as markdown_extension.

Docstrings

Workflow Tutor foresees the usage of Google-styled Docstrings to generate a reference documentation of the project.