How To Improve Your Software Documentation by Connecting Gitlab with Mkdocs

January 21st 2021 new story

@hatembentayebhatem ben tayeb

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 😙
0 reactions

Create a Gitlab repo

This is straightforward, follow these steps:

0 reactions

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 :

0 reactions

$ 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.

0 reactions

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).

0 reactions

Creating a virtual environment

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

pip install virtualenv

0 reactions

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

0 reactions

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

Installing Mkdocs Material

Make sure that the virtual environment is active.

0 reactions

Install the mkdocs material with this command : pip install mkdocs-material.

0 reactions

This package needs some dependencies to work .. install them by using a requirement.txt file, copy-paste the dependencies list to filename requirements.txt

0 reactions

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

Install them all with one command :

pip install -r requirements.txt

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

0 reactions

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

0 reactions

|--auto_docs
    |--- docs
    |--- mkdocs.yml

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.

0 reactions

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.

0 reactions

Create the CI/CD file

Gitlab uses a YAML file — it holds the pipeline configuration.

0 reactions

The CI file content:

0 reactions

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

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.

0 reactions

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.

0 reactions

All things were done 🎉 🎉 😸 !

0 reactions

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.

0 reactions

So … create a new file called .gitignore and add these lines:

0 reactions

auto_docs/ 
requirements.txt

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 😢.

0 reactions

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)

0 reactions

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

0 reactions

Originally published on: https://hatembentayeb.hashnode.dev/deploying-a-dockerized-angular-app-with-github-actions-1

0 reactions

Share this story

Read my stories

Join Hacker Noon

Create your free account to unlock your custom reading experience.

How To Improve Your Software Documentation by Connecting Gitlab with Mkdocs

How To Improve Your Software Documentation by Connecting Gitlab with Mkdocs

@hatembentayebhatem ben tayeb

Create a Gitlab repo

Setting up the environment

Creating a virtual environment

Installing Mkdocs Material

Setting up the CI/CD

Create the CI/CD file

Recommend

ci-templates - templates for Gitlab CI pipelines — ci-templates documentation

How to manage your software documentation with docz!

Connecting APRS apps to a software TNC over your network

How Agile Software Development Can Improve Your Client’s Experience

Easy GraphQL API Documentation with SpectaQL and GitLab Pages

Build Your Python Project Documentation With MkDocs

GitHub - IBM/monitor-hands-on-lab: This is an MkDocs web site to open source the...

Building Python Project Documentation With MkDocs

Documentation 101: creating a good README for your software project

Video: Connecting Minds Interview with Eppendorf's Co-CEO - Software AG | Softwa...

About Joyk