Documentations are essential for building softwares, in fact documentation is also part of the software you design and develop. It is what differentiate a good software from not a good one.
In this tutorial we will be learning how to use a nice library called mkdocs to generate documentations for our software project. As the name goes, it is for markdown documentation. We will then see how to host our documentation on Github Pages.
Let us start
Installation of Mkdocs
Mkdocs is available on pypi so you can install it with pip as follows
pip install mkdocs
It comes with a CLI that we will be using to generate and build our documentation from markdown or .md files.
Creating a Project
First we start with creating a new project for our documentation. It is recommended that you give the same name as your library or package. In order to create a new project you can use the new command from the CLI as follows
mkdocs new hello-pkg
This will generate two important files,
- the docs directory where you will place in all your markdown files for your documentation and
- a mkdocs.yml file where you will specify your configuration
Configuring with mkdocs.yml
The mkdocs.yml file will contain some important things by which mkdocs will use to build your documentation. A simple and basic example of content in the mkdocs.yml file involves
site_name: hello-pkg
site_url: https://example.com/
nav:
- Home: index.md
theme: readthedocs
- site_name : name for the site mostly it must correspond to the package/library name
- site_url: where you will host the documentation, in our case it is github eg https://username.github.io
- nav: this directs the different navigation for the documentation such as the Home, API, User Guide etc
- theme: what theme to use.
In order to add a theme like readthedocs you can specify it at the theme section. Readthedocs is a common theme for most software documentation so it is highly recommended.
Previewing Your Documentation
With mkdocs, you can preview what you have done so far using the serve command. This will spin up your documentation and serve it on your localhost port 8000.
mkdocs serve
By default the theme would be the one specified by mkdocs except you change it to readthedocs or material design docs.
Adding Multiple Pages as Tabs
An important file it must have in the docs folder is an index.md file. You can then add multiple markdown files which you can connect to the main page via the nav section in your mkdocs.yml file. This will generate each page and provide a tab for it in the menu bar
site_name: hello-pkg
site_url: https://example.com/
nav:
- Home: index.md
- User Guide: userguide.md
- About: about.md
theme: readthedocs
Building Your Documentation
To build your documentation you can use the mkdocs build command. This will convert the markdown files into html and css files contained within a site directory which you can upload to your website, or any static code website such as Github pages.
mkdocs build
Publishing or Deploying Your Documentation
After commiting your docs to github you can use mkdocs to also deploy your documentation to GitHub Pages via the gh-deploy command. This works for only Github account holders.
mkdocs gh-deploy
To conclude we have seen how to generate very nice documentation using MKDOCS from normal markdown files. You can also check out the video tutorial below