DEV Community

loading...
Cover image for Automate your Documentation with Gitlab and Mkdocs

Automate your Documentation with Gitlab and Mkdocs

hatem ben tayeb
Archlinux User | Devops engineer | Technical writer | Automation enthusiast | IaaC | CaaC | GitOps
ใƒปUpdated on ใƒป3 min read

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
  • Hit create

Now clone the project by copying the URL and run this command :
$ git clone https://gitlab.com/auto_docs.git

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.

$ cd auto_docs/
$ virtualenv autodocs
$ source autodocs/bin/acivate

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

Babel==2.8.0
click==7.1.1
future==0.18.2
gitdb==4.0.4
GitPython==3.1.1
htmlmin==0.1.12
Jinja2==2.11.2
joblib==0.14.1
jsmin==2.2.2
livereload==2.6.1
lunr==0.5.6
Markdown==3.2.1
MarkupSafe==1.1.1
mkdocs==1.1
mkdocs-awesome-pages-plugin==2.2.1
mkdocs-git-revision-date-localized-plugin==0.5.0
mkdocs-material==5.1.1
mkdocs-material-extensions==1.0b1
mkdocs-minify-plugin==0.3.0
nltk==3.5
Pygments==2.6.1
pymdown-extensions==7.0
pytz==2019.3
PyYAML==5.3.1
regex==2020.4.4
six==1.14.0
smmap==3.0.2
tornado==6.0.4
tqdm==4.45.0
Enter fullscreen mode Exit fullscreen mode

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 :

|--auto_docs
    |--- docs
    |--- mkdocs.yml
Enter fullscreen mode Exit fullscreen mode
  • 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 http://locahost:8000 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:

stages :
  - build
pages:
  stage: build
  image:
  name: squidfunk/mkdocs-material
  entrypoint:
    - ""
  script:
    - mkdocs build
    - mv site public
  artifacts:
    paths:
      - public
  only:
    - master
  tags:
    - gitlab-org-docker
Enter fullscreen mode Exit fullscreen mode

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:

auto_docs/ 
requirements.txt
Enter fullscreen mode Exit fullscreen mode

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 ๐Ÿ˜บ ๐Ÿ˜!

Discussion (1)

Collapse
teotcd profile image
JedDevs

Great Post! Me and our team found Mkdocs to be a lifesaver, especially as we work so collaboratively and remotely.