Week 1 Assignments

Student Agreement

The student agreement is committed to the git repository as part of the personal site in the "About" section.

Work Through a Git Tutorial

I have previous experience with git. But it has been a while since I have used it regularly on a project. I worked through the following as a refresher.

Initial connection to the Fabcloud GitLab site - using the web browser interface and fablabs.io credentials
Checked git command line setup - usable git available in mac terminal
Tested clone repository
- Took a little time to verify command line connection to gitlab. Git hosting environments may be set up in different ways, so it was not clear at the outset whether login credentials would support the connection. Confirmed with instructor that ssh setup was needed and proceeded with setup.
- Connection and initial clone worked fine with ssh setup
Tested basic git operations for add, commit, push with command line
- Also tested branch / checkout operations
Tested basic git operations within IDE - VS Code
Regular use of git commands in creating the personal site

Build Personal Site in the Class Archive

I am fairly familiar with basic HTML development. I explored a variety of prevous student sites in order to get a sense for how things might be organized and takeaways for site design / building. I noted that a fair number of previous students had used the MkDocs static site building tool.

The idea of using markdown to focus a bit more on content seemed interesting, so I started to explore MkDocs for use in developing the personal site.

Setting up MkDocs

Python Install

MkDocs runs in Python, so a Python setup was needed for local development.

Recent macs have a python installation (note that is accessed as python3 and pip3), but it is a little dated
Other primary options for install were using homebrew or the direct python installer
I was a little wary of using a package installer (homebrew for mac programs) to manage another package installer (pip for python packages)
I chose to do a direct install of Python

Python venv

It is still nice to maintain a clean environment. I was not certain what Python packages would actually wind up being used.

I had noticed several ways that Python maintains different package environments - such as venv, virtualenv, and pyenv.
These enable you to manage installed packages on a per-project basis
venv is packaged with recent Python versions, so I selected that one

A virtual environment is created by executing the venv module:

python -m venv /path/to/new/virtual/environment

Once created, the environment is activated by invoking the /bin/activate command from where that environment was set up. This adds a tag to the start of the shell prompt as a reminder that the virtual Python environment is active. You can then deactivate to close the virtual environment. For example, I created one for MkDocs

[~/Documents/FabAcademy2025/gitlab-site/david-wilson]
> source ~/Documents/FabAcademy2025/python/venv/mkdocs/bin/activate

(mkdocs) [~/Documents/FabAcademy2025/gitlab-site/david-wilson]
> 

... install / use mkdocs packages and functionality ... 

(mkdocs) [~/Documents/FabAcademy2025/gitlab-site/david-wilson]
> deactivate

[~/Documents/FabAcademy2025/gitlab-site/david-wilson]
>

Using MkDocs Locally

With Python in place, I worked on setting up MkDocs. I tested the setup locally first on my workstation.

I installed the packages for MkDocs (within the venv I had set up)
I worked through the MkDocs getting started guide
To practice on writing content in markdown instead of HTML, I translated the student HTML site provided on gitlab in the public direcory into a MkDocs site

MkDocs provides a local web server, so that you can see the live updates in your browser as you go.

(mkdocs) [~/Documents/FabAcademy2025/gitlab-site/david-wilson]
> mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
WARNING -  Doc file 'assignments/week01.md' contains a link
           '../img/sample-photo.jpg', but the target 'img/sample-photo.jpg' is
           not found among documentation files.
INFO    -  Documentation built in 0.15 seconds
INFO    -  [07:22:10] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [07:22:10] Serving on http://127.0.0.1:8000/

Using MkDocs with GitLab

Once I had the local version of MkDocs going reasonably well, I explored how to set up MkDocs with the Fab Academy GitLab platform. It took some time to understand the GitLab CI/CD process, in order to be able to set things up properly.

When you use git to send change(s) to GitLab, it triggers a series of processing steps on GitLab. The steps follow the instructions in the .gitlab-ci.yml file on the GitLab site. GitLab's CI/CD can do a lot of complex things to get things ready for update / deployment.

It took some time to understand the CI/CD process and what all the commands were doing, but I followed the student-template-mkdocs Template that had been used previously in Fab Academy. Once I understood it better, I tailored it a bit for my setup.

Using Material Theme with MkDocs

MkDocs comes with two default themes for documentation sites. But it also has some community developed themes. A popular theme that adds a lot of functionality is the Material for MkDocs theme.

I set up and tested the Material for MkDocs theme locally
Then made the updates needed to run with the GitLab CI/CD process and tested with the default MkDocs template site

Personal Site Content Development

Once MkDocs with Material Theme was set both locally and with GitLab, I was finally in position to do primary content updates for the assignments. This involved a fair bit of practice in using markdown, MkDocs and Material Theme capabilities, and git commands. The outcome is visible on the site, but highlights are:

Developed general navigation structure for the site
Tested out theming / configuration options
Added content for primary assignment elements
- Student agreement
- Week 1 site development
- Final project ideas