1. Gestion de projet et documentation#

This week I worked on defining my final project idea and started to getting used to the documentation process.

Establish the worflow with gitlab#

Installing WSL#

I dont have the place on my hardrive needed to install a proper linux distribution on a new partition.
But it is now (2024, windows 11) possible to install Windows Subsystem for Linux (WSL).
Enabling the possibility to run the bash shell and the Linux binary executables directly on windows.
To install it, you just need to open a Windows Teminal in Admin mode (avaible by right-clicking on the Windows Icon) and the run the command : wsl --install

And then to reboot the system.

It is going to install ubuntu either.

Goot to know : git and OpenSSH are already installed with the wsl.

Quick instructions on PCWorld
More informations on Ubuntu website and on Microsoft website

Installing git#

If you need to install the last version of git :
By the command sudo apt-get install git in the terminal.
( sudo is used to run a command in administrator mode )

Configure git#

The full name and email address should match the ones you use in GitLab. In your terminal, add your full name. For example:

git config --local user.name "Alex Smith"

Add your email address. For example:

git config --local user.email "your_email_address@example.com"

To check the configuration, run:

git config --local --list

To check your configured Git settings, run:

git config user.name && git config user.email

After you set your name and email address, you should add an SSH key. See Use SSH keys to communicate with GitLab.

All this instructions from the gitlab website

You can do exactly the same command with --global but for this you need first to configure the connexion with git as following :

SSH#

Install SSH#

To make SSH working you need to generate an SSH key pair, with the command ssh-keygen -t ed25519 -C "<comment>"

-t ed25519 is used to specify the format of the key , there is different options and the gitlab tutorial say that the ED25519 key is the best one.

You can chose the file where you want to save the key or just chose the file name suggested.
Then you have to chose a passphrase and it should be ok.

Add an SSH key to your GitLab account#

  • Sign in to GitLab.
  • On the left sidebar, select your avatar.
  • Select “Edit profile”.
  • On the left sidebar, select “SSH Keys”.
  • Select “Add new key”.
  • In the “Key box”, paste the contents of your public key. If you manually copied the key, make sure you copy the entire key, which starts with ssh-rsa, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, sk-ecdsa-sha2-nistp256@openssh.com, or sk-ssh-ed25519@openssh.com, and may end with a comment.
  • In the “Title box”, type a description, like Work Laptop or Home Workstation.
  • Select Add key.

(From gitlab tutotiral)

Connect to GitLab#

To connect to GitLab you need to prompt this command : ssh -T git@gitlab.com
If the connexion is well established you should haveWelcome to GitLab, @simon.hanin!` as a reponse in the terminal.

Git clone Via SSH#

(Just follow the instruction on GitLab Doc that are very clear )

Every day routine for Git :#

git pull to Add all changes to commit :
git add -A
git commit -m “COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT”
Send changes to remote server :
git push
And you can use git status to see what are the modifications between the last version and your local version

Mkdocs#

Install mkdocs with apt-get install mkdocs

Run mkdocs serve from the directory of the site.

But I get this error : ERROR - Config value: 'theme'. Error: Unrecognised theme name: 'spacelab'. The available installed themes are: mkdocs, readthedocs

I had to install mkdocs-bootswatch and for this i needed to install pip : sudo apt install python3-pip
Then installing mkdocs-bootswatch : pip install mkdocs-bootswatch

Creating presentation page#

Learning some markdown code#

Just followed the example page.

I had an issue with the paragraph : if I go to next line in my editor it doesn’t appear next line on the webstie.
The solution is to insert two spaces at the end of the line.

Good to know : to insert inline code in a mage you need to put the text between grave accents, with the command alt gr+µ on the belgian windows keyboard.

Also, there is not markdown command to add some colors in the text but we can use html :
<span style="color:red">text in red</span> = text in red
<span style="background:yellow">text with yellow backroung</span> = text with yellow backroung

Adding an image#

I took a picture of me from my computer that I had already cropped with word.
The image resolution is 440x438 and the weight is 29kB.
I reducet it with ImageMagick, and the command convert -resize 200x photo-simon-440x438.jpg photo-simon-200x.jpg

Then adding the image on the proper folder and display it on the website with the mardown command ![simon](/images/photo-simon-200x.jpg)

Note: another nice way to recize is to use percent if you dont want to check the pixels size and just reduce the size of half for exemple : convert -resize 50% photo-simon-440x438.jpg photo-simon-half.jpg

Documentation workflow and AI#

I tried to write all the important information on a draft version during the work. As said before my writting english skills are very approximative so I decided to use Mistral AI as a tool to correct myself and learn some english grammar.