2. Project management¶
This week I worked on defining my final project idea and getting used to the documentation process using GitLab and MkDocs.
Linking your repository and Gitlab¶
GitLab is a web-based DevOps platform that provides a complete CI/CD (Continuous Integration / Continuous Delivery) pipeline, version control, issue tracking, and collaboration tools in one application.
It is built around Git, a distributed version control system, and helps developers manage their code, collaborate with team members, and automate software delivery processes.
Create project folder¶
mkdir the folder name
open project folder
cd the folder name
Use the cd command to navigate to the home directory and jump around from using the various cd commands
Steps to Set Up GitLab with SSH and MkDocs¶
Key Features Repository Management – Host and manage Git repositories with fine-grained access control.
Issue Tracking – Organize tasks, bugs, and feature requests in one place.
CI/CD Pipelines – Automate build, test, and deployment stages.
Merge Requests (MRs) – Review and discuss changes before merging into the main codebase.
Wiki & Documentation – Create and maintain project documentation.
Project Analytics – Monitor progress, code quality, and more. Below are the steps I followed to connect my local environment to GitLab using SSH keys and initialize MkDocs for project documentation.
In the terminal, I ran the following command to generate an SSH key:
ssh-keygen -t ed25519 -C "your_email@example.com"
I then added the public key to my GitLab account under Settings → SSH Keys. Adding SSH Key to GitLab
2. Clone the Repository¶
Next, go to the gitlab.fabcloud.org repository > copy Clone with SSH
After setting up the SSH connection, I cloned my project from GitLab using:
git clone git@gitlab.fabcloud.org:your-repository.git
3. Install MkDocs¶
MkDocs is a static site generator that's designed specifically for creating project documentation.
It is written in Python and uses simple Markdown files to build fast, responsive websites. MkDocs is popular for technical documentation because it’s easy to set up, clean in design, and integrates well with version control tools like Git.
pip3 install mkdocs
4. Create the Documentation Structure¶
To initialize MkDocs, I used the following command:
mkdocs new docs
5. Build and Serve the Documentation¶
To preview the site locally, I ran:
mkdocs serve
6. Push Changes to GitLab¶
After committing my changes, I pushed them to the remote repository using:
git add . git commit -m "Initial commit with MkDocs" git push origin main
This created the following:
A project directory: /yryszhan-sansyzbay¶
A config file: mkdocs.yml¶
A folder and a file: /docs/index.md¶
The next step is to create a file from the Gitlab repository. Call it .gitlab.ci.yml and when it gives you an option to 'Apply a template' choose HTML.