Skip to content

01 : Project Management#

1. Summary#

Hero Shot#
Learning Outcomes#

What did I learn this week ?

  • Subject 1 :
    • 1
    • 2
  • Subject 2 :
    • 1
    • 2
  • Subject 3
    • 1
    • 2
Lecture Content#

During the first lecture, we learned some project management tools. I present below the ones the most important ones according to me.

Project Management Principles#

  • SPIRAL DEVELOPMENT

    Develop your project by iterations. Each iteration result must be seen as a complete project. Each iteration adds complexity.

  • SUPPLY VS DEMAND

    Allocate a fixed amount of time to your tasks before starting doing it.

  • Parallel Development

    Work on different part of your project at the same time instead of finishing a part before starting another.

  • TRIAGE

    If you are out of time, take the time to select which part of the project you give up.

Documentation#

Each one of the graduated student from Fab Academy I met told me many times that the most important and life changer thing they learnt during the formation was... Documentation.

Since I followed a course inspired by the Fab Academy called FabZero (more info here), I already have an idea of the importance of the documentation process. I also know some tools as GitLab, Markdown and MkDocs which I use for my PhD thesis documentation.

However, I would like to learn new tools that would allow me to go further (such as the HTML language) but to be coherent with the spiral development mindset, I will begin to develop my website with the tools I already know.

Version Control with Git and GitLab#

Git is a powerfull version control tool. It allows one to save its work at different stages, to try different ideas and to navigate easily between these stages or versions.

GitLab is an open-source online Git-repository with extra features such as issue tracking, website hosting, code editing, ...

GitLab CI, which is the best feature of GitLab according to Julian, allows one to automatically run tasks each time a commit is pushed. In our case it builds our website with some instructions contained in the .gitlab-ci.yml file each time we push modifications on our repository.

2. Assignment#

This first week's asignments are :

  • Plan and sketch a potential final project
  • Download, read, and sign the student agreement then commit the file to your repository
  • Work through a git tutorial
  • Build a personal site in the class archive describing you and your final project

Below you will find the achievement of the latter.

2.1. Potential Final Project#

You can find my first idea of a final project here.

2.2. Student Agreement#

You can find the signed student agreement here.

2.3. Git Tutorial#

During the course FabZero, I documented the tutorial I followed to install and use Git. I read it today to refresh my memory and followed it for this website. You can find the documented tutorial on my FabZero webpage.

2.4. Building a website with MkDocs#

2.4.1. Initialisation#

If you are new to MkDocs, check the Getting Started page.

To start using MkDocs, I have to create a new mkdocs project. However, the repository I'm working with already contains a website template including an index file. Therefore I will not use the
mkdocs new <project_name> command but simply creates an empty mkdocs.yml file and add the strict minimum content which is a site name line :

mkdocs.yml
site_name: Jonas Grimaud - Fab Academy

Now I can run mkdocs serve to verify everything is working correctly and I get the following error message :

Windows Powershell Terminal
Windows PowerShell
Copyright (C) Microsoft Corporation. Tous droits réservés.

Installez la dernière version de PowerShell pour de nouvelles fonctionnalités et améliorations ! https://aka.ms/PSWindows

PS C:\Users\subni\Documents\FabAcademy\jonas-grimaud> mkdocs serve
ERROR   -  Config value 'docs_dir': The path 'C:\Users\subni\Documents\FabAcademy\jonas-grimaud\docs' isn't an existing
directory.

Aborted with a configuration error!

I understand that by default MkDocs is waiting for the index file to be in a docs relative directory while Fab Academy template's directory is named public.

By checking the MkDocs documentation website we can see that it simply requires a modification of the docs_dir variable to modify the expected name of the documentation files directory.

First tries

Let's add the following line in the mkdocs.yml file :

docs_dir = 'public'

and run again mkdocs serve. I receive the following error message : 

PS C:\Users\subni\Documents\FabAcademy\jonas-grimaud> mkdocs serve
Error: MkDocs encountered an error parsing the configuration file: while scanning a simple key
in "C:\Users\subni\Documents\FabAcademy\jonas-grimaud\mkdocs.yml", line 3, column 1
could not find expected ':'
in "C:\Users\subni\Documents\FabAcademy\jonas-grimaud\mkdocs.yml", line 3, column 20

Of course. I know remember that the assignation symbol in MkDocs is : and not = therefore I modify the second line of the mkdocs.yml file :

docs_dir : 'public'

and run a third time mkdocs serve and it finally works :

PS C:\Users\subni\Documents\FabAcademy\jonas-grimaud> mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.53 seconds

However one should better rename the public directory in a docs directory and let the MkDocs docs_dir to default value (which is docs) otherwise some conflict may appear between Gitlab CI and Mkdocs as explained below.

2.4.2. Template Modifications#

Note

Changing extensions or deleting/creating are probably equivalent because when renaming .html to .md, the computer creates a .md file with the same content and then deletes the .html one. The process of renaming instead of manually deleting/creating is just quicker on the user side.

One of the interest in working with MkDocs is that it allows one to edit its webpages using MarkDown (which is an easier to read and write language than HTML).

However, the default files contained in the initial repository built by the Fab Academy are .html files. Of course I could simply delete them and create new .md files but it seems easier to just convert them, which is what I do by simply changing the filenames extensions from .hmtl to .md and without changing the content (it should work since MkDocs knows how to interpret HTML language even in .md files).

It works but I notice something weird. The top of the webpages looks like that :


There are two navigation bars...


I check the content of my index.md file and find out the following lines coming from the Fab Academy template :

Info

A webpage directly written in HTML language requires instructions for everything and does not automatically creates a navigation bar. These HTML lines play this role.

index.md
<div class="navbar">
    <div class="navbar-inner">
        <a href="index.html">Weekly Assignments</a>
        <a href="final-project.html">Final Project</a>
        <a href="about.html">About me</a>
    </div>
</div>


As MkDocs automatically creates a navigation bar using your files organisation structure I either have to delete the navbar HTML code or disable the default MkDocs navigation bar. It is easier for now to delete the HTML code lines.

2.4.3. Customizing your website#

Now that Mkdocs is correctlt installed and the template correctly modified to work fine with MkDocs, I can start customizing my website.

First of all, I add some meta-informations in the mkdocs.yml. Its content looks like that :

mkdocs.yml
site_name: Jonas Grimaud - Fab Academy
site_description : My Fab Academy 2026 Student Documentation Website
site_url : https://fabacademy.org/2026/labs/ulb/students/jonas-grimaud/
repo_url : https://gitlab.fabcloud.org/academany/fabacademy/2026/labs/ulb/students/jonas-grimaud
site_author : Jonas Grimaud
docs_dir : public
Installing a theme and its features#

For visual customization, I will install a theme. According to me, the most complete and easy to custom one is MkDocs-Material. To use a theme you first need to install it on your computer by running the following command in your terminal :

Windows Powershell Terminal
pip install mkdocs-material

where the last term is the name of your theme (here mkdocs-material).

Now I will indicate to MkDocs to use the installed theme by adding the following lines in the mkdocs.yml :

mkdocs.yml
theme:
    name: material

Moreover, each them proposes some easily customizable features (check your theme documentation). Therefore I added the lines below :

mkdocs.yml
theme:
    name: material
    extra:
        include_sidebar: true 
    components:                
        title: False
    font:
        text : Fira Mono
        code : Terminus
    palette: 
        scheme : default
        primary: blue grey
        accent : cyan
    features:
        - navigation.tabs
        - navigation.top
Gitlab CI modification#

Now that my theme is working correctly locally, I would like to deploy my online website. However, I only installed the theme on my own computer. Therefore I have to tell to the GitLab CI to install the same theme during the deployment pipeline. Hopefully Julian posted new templates for the ones who would like to use static website generator such as MkDocs containing the required .gitlab-ci.yml modifications :

.gitlab-ci.yml
    image: python:3.11-slim

    before_script:
    # install Git for the mkdocs revision plugin
    - time apt update && apt-get install -y git
    # Install mkdocs and theme
    - time pip install -r requirements.txt

    test:
    stage: test
    script:
    - time mkdocs build --site-dir test
    artifacts:
        paths:
        - test
    rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
        when: never

    pages:
    stage: deploy
    variables:
        ENABLED_GIT_REVISION_DATE: "true"
        GIT_DEPTH: 0
    script:
    - time mkdocs build --site-dir public
    artifacts:
        paths:
        - public
    rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

You also need to create a requirements.txt file containing the theme you would like to install :

requirements.txt
# Documentation static site generator
mkdocs ~= 1.6

# Add your custom theme if not inside a theme_dir
# (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
mkdocs-material ~= 9.7

# Plugins
mkdocs-git-revision-date-localized-plugin ~= 1.5.0
Markdown Extensions#

Some nice features of MkDocs Material requires to install markdown extensions. These can be installed by simply adding the following lines on the mkdocs.yml file :

mkdocs.yml
markdown_extensions:
    - extension 1
    - extension 2
    - ...

In this section you will find the different features I use and the required markdown extensions.

Admonitions#

Admonitions are boxes that allows one to add some warnings, notes, remarks, etc. They can be on the side in order to not interfer too much with the text or they can be in the center of the page to be highly visible.

Here is an example of warning admonition.

Warning

"Document everything yo do" does NOT mean you must document your bio-breaks.

whose Markdown code is :

Warning Admonition Code
!!! warning

    "Document everything yo do" does NOT mean you must document your bio-breaks.


Here is an example of a info side note.

Side note info

Latin is a quite cool language.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

and the Markdown code is :

Info Side Note Code
    !!! info inline end "Side note info"

        Latin is a quite cool language.

The required extensions are :

mkdocs.yml
markdown_extensions:
    - admonition
    - pymdownx.details
    - pymdownx.superfences

To allow internal links to sections of a webpage, i.e. create links that send to a section of another page of my website, I added the permalink extension :

mkdocs.yml
markdown_extensions:
    - toc:
        permalink: "#"

2.4.4. Further Customization with Extra CSS#

Colors#
Fonts#

https://wehtt.am/fonts/ https://fontmeme.com/fonts/qonquer-font/