How To Improve Your Software Documentation by Connecting Gitlab with Mkdocs

Producing documentation may be painful and need a lot of time to write and operate. In this story, i will share with you, my way of generating docs using the devops approach. To make life easier, we will explore the art of automation 😃.

Let’s go folks 😙

Create a Gitlab repo

This is straightforward, follow these steps:

• Log in to your GitLab
• Click new project
• Give it a name: auto_docs
• Initialize it with a README.md file
• Make it public or private

Now clone the project by copying the URL and run this command :

Setting up the environment

I’m using a Linux environment but it is possible to reproduce the same steps on a Windows machine.In order to follow me, you need a set of tools that must be available on your machine … make sure to to have python3 installed, I have python 3.8 (latest).

Creating a virtual environment

The easiest way to set up a virtual environment is to install virtualenv python package by executing 

pip install virtualenv

 .

Navigate to your local GitLab repository and create a new virtual environment.

Installing Mkdocs Material

Make sure that the virtual environment is active.Install the mkdocs material with this command : pip install mkdocs-material.This package needs some dependencies to work .. install them by using a requirement.txt file, copy-paste the dependencies list to filename requirements.txt

Install them all with one command : 

pip install -r requirements.txt

Now it’s time to create a new mkdocs project 😅.

Run this command : mkdocs new . and verify that you have this structure :

• The docs folder contains the structure of your documentation, it contains subfolders and markdown files.
• The mkdocs.yml file defines the configuration of the generated site.

Let's test the installation by running this command : 

mkdocs serve

 . The site will be accessible on  and you should see the initial look of the docs.

Setting up the CI/CD

let’s enable le CI/CD to automate the build and the deployment of the docs. Notice that GitLab offers a feature called gitlab pages that can serve for free a static resource (HTML, js, CSS). The repo path is converted to an URL to your docs.

Create the CI/CD file

Gitlab uses a YAML file — it holds the pipeline configuration.The CI file content:This pipeline uses a docker executor with an image that contains mkdocs already installed… mkdocs build the project and put the build assets on a folder called site … to be able to use GitLab pages you have to name your job pages and put the site assets into a new folder called public.

For tags: check the runner's section under settings → CI/CD →Runners and pick one of the shared runners that have a tag GitLab-org-docker.

All things were done 🎉 🎉 😸 !Oh ! just one thing … we forgot the virtual environment files .. they are big and not needed on the pipeline … they are for the local development only. The mkdocs image on the pipeline is already shipped with the necessary packages.So … create a new file called .gitignore and add these lines:

The auto_docs folder has the same name as the virtual environment .. don't forget 😠! you will be punished by pushing +100Mi 😝 and you will wait your whole life to complete the process haha 😢.

Now run git add . && git commit -m "initial commit" a && git push … go to your GitLab repo and click CI/CD → pipelines, click on the blue icon and visualize the logs .. once the job succeeded, navigate to settings -> pages and click the link of your new documentation site (you have to wait for 10m~ to be accessible)

Finally, I hope this was helpful! thanks for reading 😺 😍!

Originally published on: