DEV Community

Cover image for Automate your Documentation with Gitlab and Mkdocs
hatem ben tayeb
hatem ben tayeb

Posted on β€’ Edited on

21 5

Automate your Documentation with Gitlab and 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
  • 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 😺 😍!

Image of Datadog

The Essential Toolkit for Front-end Developers

Take a user-centric approach to front-end monitoring that evolves alongside increasingly complex frameworks and single-page applications.

Get The Kit

Top comments (1)

Collapse
 
jeddevs profile image
Theo β€’

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

Postmark Image

Speedy emails, satisfied customers

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up

πŸ‘‹ Kindness is contagious

Please leave a ❀️ or a friendly comment on this post if you found it helpful!

Okay