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 : $ 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== click== future== gitdb== GitPython== htmlmin== Jinja2== joblib== jsmin== livereload== lunr== Markdown== MarkupSafe== mkdocs== mkdocs-awesome-pages-plugin== mkdocs-git-revision-date-localized-plugin== mkdocs-material== mkdocs-material-extensions== b1
mkdocs-minify-plugin== nltk== Pygments== pymdown-extensions== pytz== PyYAML== regex== six== smmap== tornado== tqdm== 2.8 .0 7.1 .1 0.18 .2 4.0 .4 3.1 .1 0.1 .12 2.11 .2 0.14 .1 2.2 .2 2.6 .1 0.5 .6 3.2 .1 1.1 .1 1.1 2.2 .1 0.5 .0 5.1 .1 1.0 0.3 .0 3.5 2.6 .1 7.0 2019.3 5.3 .1 2020.4 .4 1.14 .0 3.0 .2 6.0 .4 4.45 .0 Install them all with one command : Now it’s time to create a new mkdocs project 😅. pip install -r requirements.txt Run this command : mkdocs new . and verify that you have this structure : |--auto_docs
    |--- docs
    |--- mkdocs.yml The folder contains the structure of your documentation, it contains subfolders and markdown files. docs The file defines the configuration of the generated site. mkdocs.yml Let's test the installation by running this command : . The site will be accessible on and you should see the initial look of the docs. mkdocs serve http://locahost:8000 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 "" 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 and pick one of the shared runners that have a tag settings → CI/CD →Runners 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 The 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 😢. auto_docs Now run git add . && git commit -m "initial commit" a && git push … go to your GitLab repo and click click on the blue icon and visualize the logs .. once the job succeeded, navigate to and click the link of your new documentation site (you have to wait for 10m~ to be accessible) CI/CD → pipelines, settings -> pages Finally, I hope this was helpful! thanks for reading 😺 😍! Originally published on: https://hatembentayeb.hashnode.dev/deploying-a-dockerized-angular-app-with-github-actions-1

How To Improve Your Software Documentation by Connecting Gitlab with Mkdocs

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

10 Indications That You Should Invest in Automation Via APIs

10 Commandments for AI-Assisted Social Media Marketers

11 Best Automation Testing Tools to Try in 2021

12 Use Cases of AI and Machine Learning In Finance

12 Ways You Can Use Email to Nurture Leads to Conversion

132 Stories To Learn About Robotics

10 Indications That You Should Invest in Automation Via APIs

10 Commandments for AI-Assisted Social Media Marketers

11 Best Automation Testing Tools to Try in 2021

12 Use Cases of AI and Machine Learning In Finance

12 Ways You Can Use Email to Nurture Leads to Conversion

132 Stories To Learn About Robotics

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps