Code Documentation of the Future — MkDocs-Material Tutorial

3 min readMar 4, 2020

Tutorial for Mkdocs with material theme and hosting on github pages

Intro

Everyone loves frameworks and packages that have a good documentation. There are a lot of frameworks that I love their documentation, for example Django, React, Angular and many more. However, FastAPI and Pyndatic specially stood out from the rest. It was the documentation that pushed to try out FastAPI from the start. And the best part, it is so easy to create the same documentation unlike the rest.

The current documentation

The previous years I have always used sphinx to create code documentation, and you usually end up with documentation like the Flask documentation.

The other choice is ReadTheDocs.

To be honest I don’t know which one is uglier.

Mkdocs — Material Theme

Awesome layout
Mobile friendly
Amazing text search

All of that comes out of the box

Screw it lets do it

In this tutorial I am goingto use Mkdocks with material theme to create nice documentation for the middleware created to Sanic in this article here.

you can create this documentation for any project that you have.

Install

go to the root directory if your project

pip install mkdocs mkdocs-material

create a file mkdocs.yml and add to file

site_name: name-of-your-site
theme:
   name: 'material'

create a directory docs/

create a file index.md in the docs/ and the following to index.md

# Getting Started

Full code on [github](https://github.com/ahmednafies/sanic_camelcase_middleware).

## Install
    pip install sanic_camelcase_middelware

## Dependencies
* [pyhumps](https://pypi.org/project/pyhumps/)
* [sanic](https://pypi.org/project/sanic/)

## Example
    from sanic import Sanic
    from sanic_camelcase_middleware import Camelize

    app = Sanic(__name__)
    Camelize(app)

You can add any documentation you need

lets serve the docs, go to the terminal and run

mkdocs serve

open your browser and go to http://localhost:8000

lets add more pages

in docs/ add 2 files install.md example.md

install.md

# Install## pip
    pip install sanic_camelcase_middelware## pipenv
    pip install sanic_camelcase_middelware

example.md

# Full example
    from sanic import Sanic
    from sanic.response import json
    from sanic_camelcase_middleware import Camelize

    app = Sanic(__name__)

    Camelize(app)


    @app.route("/post", methods=["POST"])
    async def test(request):
        return json("is_camelcase": True, "message": request.json})


    if __name__ == "__main__":
        app.run(host="0.0.0.0", port=8000)

now we need to add the routes to these files to the mkdocs.yml

site_name: name-of-your-sitenav:
  - Getting Started: index.md
  - Install: install.md
  - Full Example: example.mdtheme:
   name: 'material'

lets serve the docs again, go to the terminal and run

$ mkdocs serve

Looking amazing right,

lets change the color to green

open mkdocs.yml

site_name: name-of-your-sitenav:
  - Getting Started: index.md
  - Install: install.md
  - Full Example: example.mdtheme:
   name: 'material'
   palette:
        primary: 'green'