Skip to content

This document is a WORK IN PROGRESS.
This is just a quick personal cheat sheet: treat its contents with caution!


Read the Docs and MkDocs

Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you.

MkDocs is a simple static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Reference(s)

Table of contents


Read the Docs

  • create a profile on readthedocs : https://readthedocs.org/accounts/signup/

  • connect your GitLab (or GitHub or whatever is supported) account: "settings" -> "connected services"

  • import your project: "my projects" -> "import a project"

  • build it


MkDocs

This section assumes your project has a docs folder in which the documentation you want to build is located:

$ cd /path/to/your/project
$ ls
    > docs # ⚠️
    > src
    > tests
    > LICENSE.md
    > README.md
    > ...

Install

Create a Python virtual environment in the git project you want to document and install mkdocs:

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ which pip && which python # make sure those binaries are in your virtual environment
(.venv) $ pip install --upgrade pip
(.venv) $ pip install mkdocs

Note

Don't forget to create a relevant .gitignore to avoid committing the .venv, e.g.: https://www.toptal.com/developers/gitignore/api/linux,macos,windows,python,vim,emacs

Config

Setup your mkdocs project:

(.venv) $ mkdocs new . # creates mkdocs.yml (holds MkDocs config), and docs/index.md (doc entry point)
(.venv) $ mv mkdocs.yml .mkdocs.yml # optional: change mkdocs config file name

Redirect your docs/index.md to your README.md (optional):

(.venv) $ cd docs
(.venv) $ ln -s ../README.md ./index.md
(.venv) $ cd ..

Create a readthedocs-requirements.txt file, for the nice plugins to come:

(.venv) $ vi docs/readthedocs-requirements.txt
    > mkdocs-material
    > mkdocs-material-extensions
    > pymdown-extensions
    > mkdocs-awesome-pages-plugin

Install the plugins requirements:

(.venv) $ pip install -r docs/readthedocs-requirements.txt

Create a readthedocs config file:

(.venv) $ vi .readthedocs.yml
    > # .readthedocs.yml
    > # Read the Docs configuration file
    > # See <https://docs.readthedocs.io/en/stable/config-file/v2.html> for details
    >
    > # Required
    > version: 2
    >
    > # Build the documentation with mkdocs
    > mkdocs:
    >   configuration: .mkdocs.yml
    >
    > # Build docs in additional formats such as PDF and ePub
    > formats: all
    >
    > # Set requirements required to build the documentation
    > python:
    >     install:
    >         # <https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions>
    >         # <https://facelessuser.github.io/pymdown-extensions/installation/>
    >         - requirements: docs/readthedocs-requirements.txt

Create some dummy file (for the example) and modify the .mkdocs.yml config file:

(.venv) $ mkdir -p docs/Test1
(.venv) $ mkdir -p docs/Test2
(.venv) $ touch docs/Test1/test1.0.md
(.venv) $ touch docs/Test1/test1.1.md
(.venv) $ touch docs/Test2/test2.md
(.venv) $ vi .mkdocs.yml
    >
    > # Project information
    > site_name: Your site name
    > site_description: A short description of your site.
    > site_author: Your name
    > site_url: Your site url (e.g. the url of your project repo)
    >
    > # Repository
    > repo_name: the name of your git repo
    > repo_url: https://your-repo-url
    >
    > # [OPTIONAL with awesome-pages plugin] Navigation
    > nav:
    >     - Home: index.md
    >     - 'Test1':
    >         - Test1.0: Test1/test1.0.md
    >         - Test1.1: Test1/test1.1.md
    >     - 'Test2':
    >         - Test2: Test2/test2.md
    >
    > # Configuration
    > theme:
    >     # <https://github.com/squidfunk/mkdocs-material>
    >     name: material
    >     language: en
    >     palette:
    >         scheme: slate
    >         primary: indigo
    >         accent: indigo
    >     font:
    >         #text: Ubuntu
    >         text: Hack
    >         #code: Ubuntu Mono
    >         code: Hack Mono
    >
    > # Plugins
    > plugins:
    >     - search
    >     - awesome-pages # <https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin>
    >
    > # Markdown extensions
    > markdown_extensions:
    >     - toc:
    >         permalink: true
    >     - abbr
    >     - admonition
    >     - codehilite
    >     - pymdownx.arithmatex
    >     - pymdownx.betterem:
    >         smart_enable: all
    >     - pymdownx.caret
    >     - pymdownx.critic
    >     - pymdownx.details
    >     - pymdownx.inlinehilite
    >     - pymdownx.keys
    >     - pymdownx.magiclink
    >     - pymdownx.mark
    >     - pymdownx.smartsymbols
    >     - pymdownx.superfences
    >     - pymdownx.snippets
    >     - pymdownx.tasklist:
    >         custom_checkbox: false
    >     - pymdownx.tabbed
    >     - pymdownx.tilde
    >     #- pymdownx.emoji:
    >     #   emoji_index: !!python/name:materialx.emoji.twemoji
    >     #   emoji_generator: !!python/name:materialx.emoji.to_svg
    >     # <https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/>

Use

  • See mkdocs help:

    (.venv) $ mkdocs -h
    

  • Build:

    (.venv) $ mkdocs build -f .mkdocs.yml
    

  • Build and Serve:

    (.venv) $ mkdocs serve -f .mkdocs.yml
                > ...
                > INFO    -  Serving on http://127.0.0.1:8000
                > ...
    

Tip

You can use linkchecker in order to make sure there is no broken links on the generated and running website: $ linkchecker http://127.0.0.1:8000

Examples

  • Abbreviations, e.g. HTML

  • Admonitions

    Note

    Example note.

    collapsible note

    Example note.

    already collapsed note

    Example note.

    Example note.

    Example note.

    Note

    Example note.

    def bubble_sort(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    

    With code block.

    Abstract

    Example abstract.

    Summary

    Example summary.

    Tldr

    Example TLDR.

    Info

    Example info.

    Todo

    Example TODO.

    Tip

    Example tip.

    Hint

    Example hint.

    Important

    Example important.

    Success

    Example success.

    Check

    Example check.

    Done

    Example done.

    Question

    Example question.

    Help

    Example help.

    Faq

    Example FAQ.

    Warning

    Example Warning.

    Caution

    Example caution.

    Attention

    Example attention.

    Failure

    Example failure.

    Fail

    Example fail.

    Missing

    Example missing.

    Danger

    Example danger.

    Error

    Example error.

    Bug

    Example bug.

    Example

    Example example.

    Quote

    Example quote.

    Cite

    Example cite.

  • Code blocks

    import tensorflow as tf
    
    1
    2
    3
    4
    5
    def bubble_sort(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    
    def bubble_sort(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    
    def bubble_sort(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    

    The range() function is used to generate a sequence of numbers.

    Ctrl+Alt+Del


  • Annotations in code blocks:

    • Annotation with and without comment:
    #!/bin/bash
    
    ################################################################################
    # Safe shell settings:
    ######################
    # see https://sipb.mit.edu/doc/safe-shell/
    set -euf -o pipefail
    
    # Put the rest of your script here
    # ...
    # (1)
    
    1. I'm a code annotation! I can contain code, formatted text, images, ... Basically anything that can be written in Markdown.
    #!/bin/bash
    
    ################################################################################
    # Safe shell settings:
    ######################
    # see https://sipb.mit.edu/doc/safe-shell/
    set -euf -o pipefail
    
    # Put the rest of your script here
    # ...
    # (1)!
    
    1. I'm a code annotation! I can contain code, formatted text, images, ... Basically anything that can be written in Markdown.

If this cheat sheet has been useful to you, then please consider leaving a star here.