How to create documentation with MkDocs for a Python project

Install

Install mkdocs-material:

poetry add --group docs mkdocs-material

Init MkDocs project:

mkdocs new .

This will create mkdocs.yml file at the root of the project, as well as docs directory with index.md in it.

Configure MkDocs to use mkdocs-material theme and apply some styling, configurations and modules to start with. Example:

# mkdocs.yaml
site_name: Galaxy Documentation
repo_url: https://github.com/Konstankino/galaxy-be
 
theme:
  name: material
  font:
    text: Ubuntu
  features:
    - header.autohide
    - navigation.sections
    - navigation.expand
    - navigation.top
    - navigation.instant
    - navigation.indexes
    - navigation.tracking
    - search.suggest
    - content.code.annotate
    - content.code.copy
  icon:
    repo: fontawesome/brands/github
  language: en
  palette:
    - scheme: default
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
      primary: teal
      accent: purple
    - scheme: slate
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
      primary: teal
      accent: lime
 
extra:
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/Konstankino/galaxy-be
 
markdown_extensions:
  - admonition
  - pymdownx.snippets:
      base_path: ["."]
      check_paths: true
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.arithmatex:
      generic: true
  - footnotes
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.mark
  - attr_list
 
copyright: Copyright © 2023 Konstankino

Serve docs locally with:

mkdocs serve

Publish docs:

mkdocs gh-deploy --force

Update GitHub Repository to display link to the documentation website in the “About” section:

CI/CD

GitHub Actions workflow to publish docs. Place under .github/workflows/publish_docs.yaml.

name: Publish Docs
 
on:
  push:
    branches:
      - main
      - dev
 
permissions:
  contents: write
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - uses: actions/setup-python@v4
        with:
          python-version: 3.x
 
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
 
      - uses: actions/cache@v3
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
 
      - run: pip install mkdocs-material
 
      - run: mkdocs gh-deploy --force

Make commands

docs-serve:
	poetry run mkdocs serve
 
docs-build:
	poetry run mkdocs build
 
docs-deploy:
	poetry run mkdocs gh-deploy --force

Task commands

  docs:serve:
    desc: Serve documentation locally.
    cmds:
      - poetry run mkdocs serve
  
  docs:build:
    desc: Build documentation.
    cmds:
      - poetry run mkdocs build
  
  docs:deploy:
    desc: Deploy documentation to GitHub Pages.
    cmds:
      - poetry run mkdocs gh-deploy --force

Add lightbox for images

Install mkdocs-glightbox:

poetry add --group docs mkdocs-glightbox

Add to mkdocs.yaml config file:

plugins:
  - glightbox
 
markdown_extensions:
  - md_in_html