How to Generate Documentations with MkDocs

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

Thanks For Your Time
Jesus Saves
By Jesse E.Agbe(JCharis)

Leave a Comment

Your email address will not be published. Required fields are marked *