Code Documentation of the Future — MkDocs-Material Tutorial

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.

Image for post
Image for post

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

Mkdocs — Material Theme

  1. Awesome layout
  2. Mobile friendly
  3. 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.md
theme:
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.md
theme:
name: 'material'
palette:
primary: 'green'

And you can do much more, to know more how you can customize your theme check here

Deploy to github pages

That is the easiest part

just make sure that your directory is version by git and connected to a remote repo on github.

go the terminal and run

$ mkdocs gh-deploy
Image for post
Image for post

your documentation are deployed on https://{your-github-username}.github.io/{repository-name}

Software Developer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store