1A. Project management¶

Planning¶

This week will be mainly about setting up my personal website. There are many ways to build my website and I have no clear idea of which framework I want to use. Instead of looking at all possible frameworks and comparing their features I will start off by using the provided MkDocs setup. While using MkDocs I will discover what I like about it and what not. If at some point I find limitations that I don’t want to live with I will use the learnings from using MkDocs to select another framework.

Tasks - Must¶

Setup my website and describe how I did it
Create a page about myself
Upload student agreement
Work with GIT

Tasks - Nice to¶

Come up with workflow to resize images for web
Create a template for future assignments
Come up with workflow to resize videos for web
Come up with a workflow to publish sketches. Sketch manually and scan or draw with a program directly?

Execution¶

MkDocs¶

Install¶

pip3 install mkdocs
pip3 install mkdocs-material #install mkdocs material theme
pip3 install mkdocs-git-revision-date-localized-plugin #install plugin

Run provided example project locally¶

add SSH key to gitlab
clone personal repository and serve mkdocs website locally

git clone git@gitlab.fabcloud.org:academany/fabacademy/2022/labs/waag/students/benjamin-doerig.git
cd benjamin-doerig
mkdocs serve

Useful links¶

By default in the material theme the footer contains links to go to the next/previous page. In an effort to keep my website as simple as possible I want to remove these links.

After a bit of reading in the docs of the material theme I found out that there is no configuration to disable this link but It’s possible to override the default footer and remove the links that way.

Create theme_overrides/partials/footer.html
Adjust mkdocs.yml to use the theme_overrides folder
Copied the original material footer.html from here and adjusted it by removing the part about the previous/next page links

The side menus are really useful for pages with a lot of content but they’re not necessary for simple pages like Home.

I did hide the side menus of Home as described in the documentation

Enable Metadata extension
Add configuration to the pages where menus should be hidden

This is how Home looks without menus:

When the menus are hidden the content area gets quite wide and as a consequence text lines get long and hard to read. I limited the content area width with the following CSS:

css .md-content { max-width: 800px; }

Enable tasklist¶

I want to use a task list for the weekly goals to easily see what I did already complete and what is still left to do.

I adjusted the Goals list at the top of this page to be a task list

Change colors¶

What kind of colors do I want to use? It’s a simple question but It turned out to be difficult to answer. I did read a bit about color palettes and looked at some examples but it feels like I could spend a lot of time on this topic. For now I decided to stop going down this rabbit hole and keep things simple. I just change the primary color configuration in mkdocs.yml. If I want more fine grained control over the colors in the future I can add my own color variables in css.

Links with icons¶

I regularly want to link to documentation and git commits. It would be nice to have icons for such links instead of writing something like documentation and git commit in the link text each time. To make this possible I enabled a markdown extension to be able to use icons inside the markdown files with shortcodes like :fontawesome-brands-git-alt:

MkDocs can create tabs and navigation menu items automatically by discovering all markdown files in the documentation directory. In such an automatically created navigation, elements are sorted alphanumerically. As I want to define the order of tabs and navigation items I did not use this automatic approach but instead configured navigation in mkdocs.yml

With this approach the navigation menu of the assignment page will list all the assignments. Having the documentation of one assignment + the navigation listing all the other assignments in a single page feels like a lot of content. I’d like to focus the readers attention on a single thing: Either he chooses what documentation to look at in the navigation or he reads the documentation of a specific assignment.

To achieve this I’d have to:

Create one overview page where one assignment can be chosen. I can create an extra overview page with links to the assignments.
One page (without navigation) for each week/assignment. I can hide the navigation menu by adding metadata to the markdown files like I did here

Fail

I wanted to make the overview page look the way blog post previews are ofter shown This is where things start to be a bit tricky with MkDocs. I didn’t find any existing element which could be used for the preview boxes and I didn’t find any way to extend markdown to support new elements.

It’s possible to add HTML directly inside the markdown files but that means that I’d have to write the overview page mostly in HTML and add CSS styling myself. This feels like quite a bit of work and I therefore decided to give up on the idea of separate overview/content pages for now.

Simplify inclusion of images in markdown¶

I made this change in week 9

In markdown images can be included like this:

![Image title](../images/09_MC/my_image.jpg)

I want my images to be clickable to show them full size. This can be achieved by putting the image in a link like this:

[![Image title](../images/09_MC/my_image.jpg)](../images/09_MC/my_image.jpg)

To avoid having to type all of this every time I want to include an image I created a macro to simplify things:

Install plugin: pip3 install mkdocs-macros-plugin
Add - macros to mkdocs.yml under plugins:
Create main.py in the root folder (next to mkdocs.yml)

Define macro to include images in main.py:

def define_env(env):

@env.macro
def image(path, width="100%"):
    return f"[![{path}](../images/{path}){{width={width}}}](../images/{path})"

Use macro in markdown pages
```
{{ image("09_MC/my_image.jpg") }}
```

Image workflow¶

Goal:

Avoid adding raw (full size) images to version control (There is a 10MB size limit in GitLab)
Easy way to downsize raw images to web size
Web size images will make pages load faster

Steps:

Create images/raw folder for raw images
Excluded folder from version control by listing it in .gitignore
Create resize_raw_images.sh that
- Copies all images from images/raw to images
- Uses ImageMagick to resize the images inside images to web size

GIT¶

I won’t make a GIT tutorial as I’ve already been working with it for several years.

I notice again and again that GIT commit messages are a really valuable tool when we take the time to make the messages descriptive. I find myself reading commit message quite often to understand a code base better. I decided to follow this commit message convention in my Fab Academy repositories.

Fail

Today I was combining and rewording some commits to make them clearer. When I tried to push I realized that I did change commits that I have already pushed to the remote repository. I was not able to force push because GitLab does not allow it on the master branch by default. I solved this situation by pulling and resolving the merge conflicts.

To avoid such situation I can think of 2 options:

I push only once I completed working on a certain task and from then on I won’t change commits anymore
If a task takes longer and I don’t want to have the work only locally I can work on a feature branch and regularly push. I can still change commits of the feature branch even if I pushed them. Once I completed the task I merge the feature branch into master

Assignement template¶

It makes sense to have a page with a similar structure each week. I created a template which I can use as a starting point for each assignment:

# <Title>

## Planning
<Short description of what I'm planning to do this week>

### Tasks - Must
* [ ] Necessary task

### Tasks - Nice to
* [ ] Optional task

## Execution
<Document how I completed the tasks from the planning>

## Retrospective

### What went well

### What didn't go so well

### What I want to do differently next week

To be able to embed template.md above I enable the Snippets extension.

At first it did not work because I was using the wrong path to the file to be embedded. I was assuming that the path should be relative to the docs folder but that’s not the case. The path has to be relative to the root folder: docs/assignments/template.md

Student agreement¶

I copied the student agreement from here, added my name and added it to the website in the about section. I did as well add a link to it in the footer by adjusting the footer template.

Retrospective¶

What went well¶

I managed to get the website up and running
MkDocs + Material theme are easy to use
Time boxing: Some optional tasks turned out to take longer than expected. I “parked” them to focus on other tasks
I found a lot of interesting projects/products while doing research for my final project

What didn’t go so well¶

MkDocs + Material theme can be slightly customized but bigger changes are not so easy
At times I worked multiple hours before taking a break
I missed part of the 2D/3D lesson

What I want to do differently next week¶

Remember to take a quick break every hour or so
Check my calendar daily

Last update: June 18, 2022