1. Project Management - Week 1¶
1.1. Assignments¶
Project Management
build a personal site describing you and your final project
read/sign the student agreements
1.2. Creating the website¶
1.2.1. Static-Site Generator¶
I have chosen Sphinx for documenting because it is used in many big Documentations like the Linux Kernel or Python and I wanted to try it out.
So I installed it in my Operating System (Linux), it was packaged for my Distro so no worries.
In the beginning I’ll use the Furo theme und the extensions:
MyST for writing the Docu in Markdown files
CopyButton for having a ‘copy’-button in the code-blocks
ToggleButton for toggle menus
Design for better formatting options
1.2.2. Git Setup and Site generation¶
I’ve used git many times so here a skim about my steps:
added ssh key to my FabAcademy-Gitlab Account
cloned the repo and setup a basic structure:
I chose to develop on a
development branchand then merge those changes in the main/default branch viamerge requestin Gitlab to always have a working version of the website while still uploading my changes to the repo (see Spiral Model)
git clone git@gitlab.fabcloud.org:academany/fabacademy/2025/labs/ilmenau/students/niclas-starost.git
cd niclas-starost/
git checkout -B development
sphinx-quickstart # an interactive setup of a basic structure for a sphinx-project
I’ve also chosen to separate build and source directory
this creates a basic structure for the project where:
in the build directory are the generated outputs (pdf, html, epub)
├── build/
│ ├── doctrees
│ └── html
├── make.bat
├── Makefile # for conveniently rebuilding
├── README.md
└── source/
├── conf.py # configuration options with plugins, extensions, themes, etc.
├── index.md # index with table of contents
├── _static/ # used for pictures and static items
└── _templates/
and added my files and structured it for the FabAcademy:
└── source/
├── about/ # about page and agreements
├── assignments/ # weekly assignments
├── conf.py
├── final_project/ # doc and needed files for final project
├── index.md
├── _static/
└── _templates/
Note
I used:
tree -L 2 -I 'public/'
# ^^^^^^^^^^^Ignore/exclude files/directors from view
# ^^^^ Level/depth of tree
to generate the above graphic/pictures.
after that, deleting the old public page
rm -r public/*
and for conveniently rebuilding the side with
make html, I adjusted the default make-script generated bysphinx-quickstart:this requires
rsyncandmaketo use (provided by the OS)
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
WEBSITEDIR = public
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
rsync -a "$(BUILDDIR)/html/" "$(WEBSITEDIR)/" # copy the html output to public
clean:
rm -r "$(BUILDDIR)" # remove the build directory for a clean build
then using normal git commands i added, commit and pushed it to the remote, creating a new branch
this branch is then merged via merge request, when development reaches a state, that is worth showing to the public
1.2.3. CI/CD Configuration¶
After optimising the rebuild process, it’s time to put this process in the CI/CD (Continues Integration/ Continues Development).
This means, the project is build and deployed in the same step and I don’t need to upload the build every time.
So I installed everything with
pipin anvenvlike this:
python -m virtualenv env # creates a directory 'env' with everything needed to develop in python
source env/bin/activate # activate the virtuale environment, sourcing the new PATH etc.
pip install sphinx sphinx-copybutton furo myst-parser # install sphinx, copybutton the theme and the markdown-parser
pip freeze > requirements.txt # record all package-versions for the CI
Then i changed the
.gitlab-ci.yml:
image: archlinux:latest # i just use a minimal Linux
# also the same environment I test it in
pages: # job for the pages, needs to be called like this (or else set in a sub-point)
stage: deploy
before_script:
- pacman -Syu --noconfirm python python-pip make rsync # install necessary environment in the container
- python -m venv . && source bin/activate # create a virtual environment and activate it
- pip install -r requirements.txt # install dependencies
script:
- mkdir public && make html # make the public directory and use the build script from above to create the site
artifacts:
paths:
- public # public folder is then deployed
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # only deploy on the main branch
1.2.4. Sphinx¶
1.2.4.1. Configuration¶
Configuring Sphinx is easy, there is just a conf.py where variables are defined in python and used by sphinx:
project = 'FabAcademy 2025' # Project Name
copyright = '2025, Niclas Starost' # Copyright sign on the button
author = 'Niclas Starost' # It's me
extensions = ['myst_parser', 'sphinx_copybutton'] # use those sphinx extensions, in this case a copy button for code and a markdown parser
source_suffix = { # here I accepted the .md and .rst files to be used in sphinx
'.rst': 'restructuredtext',
'.md': 'markdown',
}
extensions = ['myst_parser', # activate the extensions mentioned above
'sphinx_copybutton',
'sphinx_togglebutton',
'sphinx_design']
pygments_style = "gruvbox-dark" # used for the code highlighting
pygments_dark_style = "gruvbox-dark" # my favorite theme
html_theme = 'furo' # setting the theme
html_logo = './_static/fab_academy_logo.png' # setting the logo
html_static_path = ['_static'] # path for finding static items
html_theme_options = { # theme specific options
"navigation_with_keys": True, # enable arrow keys to move around ;D
"light_css_variables": {
"color-brand-primary": "green", # setting the theme color
},
"dark_css_variables": {
"color-brand-primary": "green",
},
}
Hint
After changes, just use make html for rebuilding in the directory with the Makefile
Tip
Use make clean when changing the theme, so the old files are deleted from the build directory (when using my make file from above)
1.2.4.2. Working with markdown¶
With MyST Syntax it is pretty easy to work with markdown and format stuff.
Cool included stuff:
Admonitions - ‘callouts’ for special sections, also tabs and web-components
Image - more image formatting options
CodeBlock - very nice codeblock-sugar
Math/Equations - directly math equation integration
One tricky thing is to work with the toctree.
1.2.4.2.1. The toctree (Table of Contents)¶
The table of content is used to find the files and list them in the sidebar. I wanted to replicate this view:
.
├── about
│ ├── about.md
│ └── students.md
├── assignments
│ ├── 3d_scanning_and_printing.md
│ ├── applicatons_and_implications.md
│ ├── assignments.md
│ ├── computer_aided_design.md
│ ├── computer_controlled_cutting.md
│ ├── computer_controlled_machining.md
│ ├── electronics_design.md
│ ├── electronics_production.md
│ ├── embedded_programming.md
│ ├── input_devices.md
│ ├── interface_and_application_programming.md
│ ├── invention_intellectual_property_and_income.md
│ ├── machine_design.md
│ ├── mechanical_design.md
│ ├── molding_and_casting.md
│ ├── networking_and_communications.md
│ ├── output_devices.md
│ ├── principles_and_practices.md
│ ├── project_development.md
│ ├── project_management.md
│ ├── system_integration.md
│ └── wildcard_week.md
├── conf.py
├── final_project
│ └── final_project.md
├── index.md
├── _static
└── _templates
In the MyST-syntax the toctree can be included in a codeblock like this:
# Your typical Markdown file
- a very important point
```{toctree}
:maxdepth: 2 <!--max depth shown-->
:hidden: <!--hidden in the current view-->
:includehidden: <!--but show included hidden TOCs-->
:caption: Contents: <!--above the TOC-->
Assignments <./assignments/assignments.md> <!--then add the files in the format 'NAME <PATH>'-->
Final Project <./final_project/final_project.md>
About <./about/about.md>
```
```{toctree}
:maxdepth: 2
:hidden:
:numbered:
Project management <./project_management.md>
Principles and Practices <./principles_and_practices.md>
Computer Aided design <./computer_aided_design.md>
Computer controlled cutting <./computer_controlled_cutting.md>
Embedded programming <./embedded_programming.md>
3D Scanning and printing <./3d_scanning_and_printing.md>
Electronics design <./electronics_design.md>
Computer controlled machining <./computer_controlled_machining.md>
Electronics production <./electronics_production.md>
Input devices <./input_devices.md>
Output devices <./output_devices.md>
Networking and communications <./networking_and_communications.md>
Mechanical design <./mechanical_design.md>
machine design <./machine_design.md>
Molding and casting <./molding_and_casting.md>
Interface and application programming <./interface_and_application_programming.md>
System Integration <./system_integration.md>
Wildcard week <./wildcard_week.md>
Applications and implications <./applicatons_and_implications.md>
Project Development <./project_development.md>
Invention, intellectual property and income <./invention_intellectual_property_and_income.md>
```
Note
Also it’s not needed to use this format, it should be sufficient to just add the file path, but in my case only this worked somehow \o.o/