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.
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'
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
your documentation are deployed on https://{your-github-username}.github.io/{repository-name}