Week 1, Project Management and Documentation
Objectives
- Plan and sketch a potential final project
- Read, sign (add your name to) the student agreement and commit it to your repo
- Work through a git tutorial.
- Build a personal website in the class archive describing yourself and your final project. Refer to the lecture material for examples.
- Upload parts 1 and 2, to the class archive.
Documentation setup
Spent the week setting up Git Hub and MkDocs and deciding how to setup the documentation site. I eventually settled on the Material theme for MkDocs as it has the most flexibility and good aesthetics.
The development of the site proceeded in a spiral development path. Initially, I started by modifying the provided html pages and adding custom pictures. This was done initially with Sublime as that is what I was familiar with helping my kid in her Computer Science class. This worked fine until my free trial of Sublime ran out and I didn't want to pay $99 to continue.
After reviewing the Fab Academy documentation, I looked closer at MkDocs and decided to give it a try. I downloaded it, did some light custimization and proved that I could add pictures, change text, update the tab icon, and push to Git with the included themes. This included installing Python and GitBash software to handle the repo setup and control. The initial development on MkDocs was done through Notepad, which worked, but was not very user friendly.
After reviewing some YouTube videos about the MkDocs'Material' theme, particularly the one from James Willett, I decided this would be a good base from which to take the project docs forward. I downloaded the package and installed it. After seeing James use VS Code as the editor for the MkDocs code, I downloaded that as well. After some initial setup and testing the platform, it seemed easy enough to use, so I invested more time in customizing the pages and adding content. I finished up by adding the Lightbox plugin to my site to have more control over the images without having to do too much editing before adding to the repo. Developed a custom Favicon (Kite One Font) and added to site.
| sample setup code | |
|---|---|
Documentation Structure Updates (3/4/25)
About 4 weeks into Fab Academy I changed the entire structure of my documentation.
Original Way
When I first setup the MkDocs site, I was building locally and they manually dragging and dropping files to the folders that were tied to the GitLab account.
When I setup the workflow, I downloaded GitBash and created a folder that I could push and pull from. I used the Fab Academy Tutorial as a guide and went through the steps of setting up an account, configuring my email, generating my SSH key, and putting into my GitLab account.
Then I downloaded Python and used that to install mkdocs and the material theme.
As I was setting up and building my site, I would use 'MKdocs serve' command to make it viewable on my Chrome browser as I was building. Then, when I was happy with my changes, I could do the 'Mkdocs build' command to created the .html files in my local drive. Then I would push them to the GitLab folder and overwrite any of the old html files. Once this manual drag and drop was complete, I would then go back to Gitbash, use the CD command to my working folder. Then I would do the following commands inside of GitLab:
git add . (to scrub the folder for all updated files to the queue)
git commit -m ‘change you did’ (to add my comments of the changes, and tell git that I wanted to push the files)
git push (to check in all of the documents I had changed to Gitlab)
Occasionally I would use 'git pull' to pull the latest files from Git locally. I only had to do this a few times when I screwed up my push with a file that was too large and had to re-sync the folders.
Initially I was editing my Mkdocs files in Notepad, but eventually migrated to VSCode
New Way
After talking to David Wilson (the other student in my lab) I found there was an easier way. He showed me that it was possible to use Git inside of VS code and have the Mkdocs build in the cloud. He helped me to setup a new folder for the Git reference, add the gitlab-cy.yml file that created the script for the site build, and build the site in the cloud.
New VS Code setup showing the .gitlab-cy.yml file.
This then made it possible to do commits directly from VS code, which is much easier than the more manual way I had been doing it. To check on build progress, I can see it happening on GitLab.
Gitlab site showing progress of past builds.
Once this was setup, I slowly migrated my content to my new folder as well as the style and colors that I previously had. It took a few hours to get all of the pictures and link references back but has made it much easier with subsequent assignments.
About Mkdocs and Markdown
Mkdocs allows you to use the Markdown programming language to automatically generate html pages for documentation websites. It makes it much easier to focus on the documentation instead of having to custom build html with associated CSS. You use the mkdocs.yml file to define the structure and pages of the site as well as any plugins or other style definitions. In my .yml file I added the 'Material' theme which gave me some more flexibility and options. I also added some extensions like "pymdownx.highlight" to allow for displaying code blocks like this:
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
For the structure of my website I have a top level with 4 sections: Home, About Me, Camera Project, and Assignments. The Camera Project is my final project for Fab Academy and has sub headers for different activities related to the project. Similarly, the Assignments section has subheadings for each week's assignment.
References:
Material Theme Lightbox Plugin
Final Project Ideation
After a deep dive of some old and new ideas, I have 2 competing ideas for a final project, and a page of other ideas too.
Photo Effect Flare Reducer
This concept is a replacement flare reducer for a DSLR camera that would allow for unique photo effects. There would be a series of LEDs that would be directed into the optical path to add color filtering. There may aslo be a telescoping element with reflective material to create prismatic flares. Examples of the effects are shown below.
Photo shot with and LED flare effect from a DSLR camera
Sketch of what this could look like including a flexible sleeve that is illuminated by side emmitting LEDs and a standard addressable white LED ring
Desert Plant Condition Monitor
This would be a plant monitoring device that could be used in desert environments to monitor plant conditions in harsh conditions such as those found in Namibia. Lithops (living rocks) are small species that grow in clumps in Namibia and South Africa and are also cultivated in lithopariums, botanical gardens, and in the home. Not much is known about the acutual conditions that these plants experience in situ, so a monitor with long range data transfer (like LoRa) may be able to uncover key insights about their habit and habitat and potentially alert conservationists if known habitats are at risk of poaching.
Lithops geyeri growing in Namibia
Potpourri- Other ideas that could be fruitful
Open source robot
Automated Chameleon Tank
Refurbed aluminum can thing
Refresh a boardgame
Mechanical fan with different tones (rotating blades)
Kinetic art
Automatic hose nozzle fertilizer dispenser
Automated Lithops Garden
Reboot inventions from the book 'The Hottest New Business Ideas For 1978'