Skip to content

Mkdocs Documentation

About MkDocs

MkDocs is a general-purpose tool for generating project documentation using Markdown files.

MkDocs vs. Sphinx

Sphinx is the initial tool I decided to use for documenting this project. I've since been experimenting with the Backstage developer portal which currently uses MkDocs for their TechDocs tool so I figured I'd experiment with MkDocs.

A few pros and cons of MkDocs with the mkdocstrings plugin over Sphinx with the autodoc extension:

Pro

  • Only uses Markdown. No more RsT, which is Python-specific, and kind of ugly. * In general, Markdown syntax is less cumbersome than RsT's. For example: [sitename](url) vs. `sitename <url>`_.
  • Works with Backstage TechDocs.
  • Easier configuration in mkdocs.yml vs. docs/conf.py
  • Extensible with many plugins including macros which I use here to substitute the view_uri in references.

Con

  • RsT markup in Python docstrings will have to be refactored to Markdown. Maybe this is a Pro.
  • Docstrings will have to be refactored from RsT to Google-style. * #: comments before members → """ docstrings """ after them (which is also supported by Sphinx autodoc) * Intersphinx references like :py:class:`~django.db.models.Model` → [django.db.models.Model](https://docs.djangoproject.com/en/3.0/ref/models/instances/#django.db.models.Model) * URL refs from `sitename <url>`_ → [sitename](url). TODO: move this down.
  • Also extensible via plugins and with any Python code you care to add to conf.py.
  • Alternatives to apidoc are not great. The closes seems to be mkdocstrings which fails to work with some DRF components.

Converting this project to MkDocs

Since my docs are already in Markdown, converting from Sphinx was easy and can mostly coexist. Here's a summary of changes I made:

See docs/requirements-mkdocs.txt. 

1
2
3
4
5
6
7
8
# bring in requirements for my app (excepting the optional database):
-r../requirements-django.txt
# stuff needed for mkdocs documentation:
Markdown==3.2.2
mkdocs-techdocs-core==0.0.13
mkdocs-macros-plugin==0.4.20
mkdocstrings==0.13.6
mkdocs==1.1.2

  • Use backstage.io's techdocs-core plugin which brings in several others.
  • Use macros plugin as described above, including this custom code which: defines view_uri based on the git repo configuration.This requires adding {{view_uri}} in URL references in the various markdown files which previously didn't have any links. You can also use macros like {{git.date}} to show the repo date.
  • Mkdocstrings for automated API documentation.
  • In mkdocs.yml add the document hierarchy that is in docs/index.rst.

Viewing MkDocs-generate content locally

This is easily accomplished. Simply use:

1
$ mkdocs serve

Publishing to RTD

Readthedocs easily supports both Sphinx and MkDocs through a configuration file. Changing this project over simply required adding .readthedocs.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
# sphinx:
#   configuration: docs/conf.py

# Build documentation with MkDocs
mkdocs:
  configuration: mkdocs.yml

# Optionally set the version of Python and requirements required to build your docs
python:
  version: 3.7
  install:
    - requirements: docs/requirements-mkdocs.txt
#   - requirements: docs/requirements.txt