1. Project management and documentation#

Table of Contents

• Summary
• Steps
  • Make a Github account
  • Install Bash
  • Git and SSH key
  • Some useful programs
    • VSCode
    • GraphicsMagick
    • SketchFab
    • Note on MkDocs
      • Installing MkDocs
      • Website theme
• Personnal site and documentation
• Issues

Summary#

This week I basically learned how to document the progress I’m making and the new tools I’m learning to use.
This is a very useful thing to know because in this PHYS F507 class we learn a lot (I really mean a lot 🤯 ) of completely new stuff at once and it’s simply impossible to remember every step.
So, the best thing to do is to document every single relevant step you’re taking and go back to your documentation later to remember what you did.
A quote from 19 century psychologist Hermann Ebbinghaus:

Humans more easily remember or learn items when they are studied a few times over a long period of time rather than studied repeatedly in a short period of time

Steps#

Sidenote: I have a Windows PC, so if you have a Mac this tutorial probably won’t work for you.

So, in this class, we needed to familiarize ourselves with documentation tools. In chronological order, we needed to :
1. Make an account on GitLab
2. Install Bash on your PC
3. Make an SSH key to link your GitLab with a copy on your computer
4. Install and get familiar with some useful programs
5. Write a personal site using Git and the help of other programs
6. Document our work and post issues

Make a GitHub account#

This step is pretty straight-forward, just go to this site and sign up as name.surname. Afterwards, go to your GitLab profile and copy your user ID in the google sheets that Mr Terwagne will have shared with you.

Install Bash#

After, you will have to install Bash, which will allow you to use programs through an UNIX command line interface (What is this? and How the heck does it work?)

It’s really useful to take some time to get familiar with the UNIX commands before you go any further, trust me.

Git and SSH key#

Now comes the complicated part. There are some tutorials on the web that I used but I’ll try to explain everything here.

First of all, why using Git to document and not just modify your website on GitLab? That’s a tough question but basically, once you get used to Git after hours and hours of practice 😵‍💫 it’s way easier and faster to work on your local copy than online. Also, having a local copy allows you to save everything and document as you go. And, finally, with the mkdocs extension (see later in this documentation) you can have a reliable preview of how your website will look like.

Here are the steps :
1. install Git
2. In Bash Shell, add your username
git config --global user.name "lukas.schieble"
3. Add your e-mail address
git config --global user.email "lukas.schieble@ulb.be"
4. Set up an SSH key
For that, you need to go to Gitlab and select your profile. After, choose edit profile. Then, you need to click on SSH key that will be on the left bar on the menu. Finally, select add a new key.
5. Clone your repository with the SSH key
For this, you will have to go to the gitlab module of the class then choose your name and press the Fork icon in the top right corner of your screen. Then, choose a namespace for your fork. To clone your repository, go back to your homepage on the gitlab of the class and select clone => clone with SSH and copy the link. Eventually, open a terminal, go to the directory where you want to clone your files and run the following command :
git clone **name of the copied SSH link**
And then, finally, you will have access to your local copy of the website

Some useful programs#

Here I’ll show you some useful Websites/programs I used to make my documentation. There are many other programs you can use but the ones I’ll show you do the job and are totally free.

VSCodium#

This text editor is where you will write your documentation. Careful : you need to save your changes in VSCodium first (CTRL+S) before you can add them to GitLab.
You will write in Markdown, here’s a tutorial and an emoji cheat sheet.

Markdown is not perfect, so sometimes if you want to, say, add a video or change the color of the text, you’ll need to writ your code in html (tuto to add a video)

To add your changes, you need to take the following steps :

• Open a shell and go to the directory containing the text file you just modified

• Use the following instructions :

GraphicsMagick#

This program allows you to compress one or more images to a smaller size to make your document less heavy.
Here’s an example (the command convert +/- append -geometry fusions 2 image files horizontally (+append) or vertically(-append) and creates a 3rd file, the command convert -resize resizes an image) :

See the Markdown tutorial to know how to add a link for a local image.
Sidenote : To add a local image, the path to follow starts at the directory of the textdoc you are modifying (in this case, the directory is ./fabzero-modules).
Markdown can’t add videos, you need to use the html synthax for that.

Sketchfab#

For the doc of your next module on 3D modeling, you might want to add your 3D models to your documentation. Don’t try to do it before doing the module 2 because I’m explaining some aspects you might not yet be familiar with. Here’s how I did it :

• Export your 3D model from OpenSCAD/FreeCAD as an .stl file
• Go to the Sketchfab website and make an account. Choose the free version, it’s largely enough. Once you’ve signed up, upload your stl file on sketchfab.
• Edit your file (change size, color) and publish it
• Once published, press the Embed button and select Copy to clipboard
  
• In the text editor program, paste the code and there you go

Note on MkDocs#

IMPORTANT INFO : The way the previewer on VsCodium shows your documentation (which is how it appears on GitLab) is not exactly the same as the final result on the FabZero website.
Here’s an example (Web on the left, gitlab on the right, the dots don’t appear on the Website and there are some synthax errors) :

Another situation where the render is not the same is for the 3D models which don’t render on GitLab but do on the website.

Install MkDocs#

To get an exact preview on how your documentation will finally look like on the Website, you need to use MkDocs. First, you have to install it using the following steps :

• Install Python and pip.
  First, check if Python is installed by typing python --version into the command line. If it’s installed, it should display Python version xyz. If it’s not installed, install it on this website. For pip, do the same thing (type pip --version into your shell). If it’s not installed, download get-pip.py and run the command python get-pip.py in your Shell.
• Once python and pip are installed, run the command pip install mkdocs. Check if the installation worked well using mkdocs --version
• Now that MkDocs is installed, go to your websites repository in the shell(in my case, the pathway is ./Users/Lukas/option_jedi/lukas.schieble) and run the command mkdocs serve. Follow the link as seen on the image below (Ctrl+click).
  

Website theme#

The standard theme of the Website is quite boring, so feel free to change it. For that, go to the mkdocs.yml file and change the theme. For my site, I used the journal theme. However, the standard mkdocs version only supports the mkdocs and the readthedocs (very nice, I recommend) design, so you could change your theme in the mkdocs.yml file but you wont’t be able to see the evolution of your website in real time anymore (mkdocs serve doesn’t work anymore). In order to change that and to be able to experiment a bit with the different themes, use the commandpip install mkdocs-bootswatch and now mkdocs will have the extensions like spacelab or cerulean among others. You can also install the dracula theme which I find very cool (too many colors however) using pip install mkdocs-dracula-theme

Change theme

Dracula theme

Personal site and documentation#

With all those powerful tools with me, I then went on to create a personal site on the class website and I started documenting my work during this first module. If youre reading this, you’ve probably already seen it 😉

Issues#

To import the issues into your GitLab, you have to go to the Fabzero module 6 and download the issues for modules 1, 2 and 3. After, go to the issues section on GitLab and import the issues (import SSV files). And there you go!
Put yourself as an assignee and select the assignment not started label.

The issues are basically a feedback to check if your documentation for each of the 5 modules is well done and which parts are missing. Once you’ve finished all the elements from the checklist, put Assignment done as a label. Your binome de soutien will then review your documentation and give you useful advices on how to improve it (template in FabZero module 6). The goal is to have all your assignments with the reviewed label.