1. Principles and Practices & Project Management¶
This week I worked on defining my final project idea and started to getting used to the documentation process. (Jan 27)
12-15 minutes
MKdocs install & Git setup¶
In addition to watching the student Bootcamp lectures and practicing surface mount soldering, over the first week of class, I took the time to set up my documentation site that you are reading currently. My documentation site was written in the Markdown language and published using GitLab CL. The site relies on MKdocs, a static site generator is written in python to create the content of the site, as well as the MKdocs Material Theme for customization.
Although the site can be edited from the online GitLab, I decided to set up Python and MKdocs on my laptop so I can work on my site locally via Visual Studio Code before publishing. My installation process started with the install of Python, Pip, Git, and MKdocs. Using the command,
git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/<your-repository>.git
I was able to clone my GitLab repository to my computer’s local drive once I had my SSH key setup. This allowed me to open and edit the files on my laptop. Despite some great documentation, I found (MKdocs Material Theme Documentation, Fab Academy GIT Simple Cheat Sheet), It would be a lie to say there wasn’t troubleshooting involved. My classmate, Graham Smith, and I discovered that a major issue we were running into was the fact that MKdocs is not compatible with the latest 3.9 version of Python, and thus we had to be running a previous instance to install MKdocs. Fortunately, this was an easy task, as we just had to uninstall the most recent instance of Python and select the older compatible, 3.8.6 version of Python from the Python downloads page.
Once my GitLab repository was cloned locally to my computer, I attempted to run a local version of the site via the command,
mkdocs serve
in Visual Studio Code’s terminal, however, I was met with two error messages directing me to install the MKdocs Material Theme and the Git revision date localized plugin. I installed both of these MKdocs plugins via pip, and after both successfully installed, I was able to run mkdocs serve and run my site locally!
Although this process of locally editing my site before pushing it publicly is unnecessary due to the ability to edit the site directly in the original GitLab, the ability to have a live, local preview of my site while editing has been a huge help to me so far, and I’m sure as I continue to update my site in the future, the preview without publicly publishing will make my life just a little easier. To further improve my Git skills, I worked through some of Gits documentation videos, which gave me a short intro to version control, and laid out the uses of Git.
SSH setup¶
To clone a Git repository locally, an SSH key must be generated on your computer and then attached to your GitLab account. GitLab has really good documentation on creating a new SSH key, and attaching it to your GitLab account. However, I was having some trouble with copying the SSH to add to my GitLab. Thanks to some research and help from my classmate, Jack Hollingsworth, we were able to find this command that can be run in Powershell to copy your SSH key.
Get-Content ~/.ssh/id_filename.pub | Set-Clipboard
The process for generating and attaching a new SSH key to your GitLab is relatively pain-free when following this documentation and using the command written above. My process involved running these commands
ssh-keygen -t ed25519 -C "<Your-SSH-Name-Here>" \\ generates a new SSH key on your computer
\\ continue to click enter when prompted with
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):
\\ then when prompted with
Enter passphrase (empty for no passphrase):
Enter the same passphrase again:
\\ enter a passphrase for your SSH key that you can remember, as you will need this password whenever you attempt to pus your site back to the GitLab
Get-Content ~/.ssh/id_filename.pub | Set-Clipboard \\ copys your new SSH key to clipboard
Once copied to the clipboard, you can paste the newly generated SSH key in your SSH key settings on GitLab, to link your computer and your GitLab. Now you can finally clone your GitLab repository locally as discussed above.
Site setup & customisation¶
After overcoming the setup issues, I was able to edit my MKdocs site locally on my laptop. My personal favorite source-code editor is Visual Studio Code, so naturally, I used this interface to edit my site files cloned from the GitLab. I started by customizing the mkdocs.yml file, a good starting place for my customization, allowing me to change the site’s name, colors, font, and logos. I also personalized my social links on this page, so when in the footer on my site, you can access all of my social platforms. I used the mkdocs.yml file as well as my About me page’s Index.MD file to become more comfortable with markdown. I found that reading the MKdocs Material Theme Documentation was incredibly helpful, as not only does it help with basic markdown/MKdocs features, but also specifically address the features available in the Mkdocs Material theme used on my site. I spent my free time throughout a weekend reading through this Material theme documentation, and messing around on these two pages on my site and started to get the hang of Markdown. After messing around with the mkdocs.yml file after reading the MKdocs Material Theme Documentation, I was able to put together a site theme that I’m happy with. I’m a big fan of the darker background, especially when looking at pictures on it, and I also think it goes great with the top black header. This combination gives the clean look on the site that I was going for.
Despite how much I liked this combination, I felt as though this grey background wasn’t sufficient enough for my site’s home page, so I used HTML to add a custom background that I edited using Pixlr. I added a gradient to the upper half of this image, allowing for a seamless transiting from the image to the black header on the site. W3Schools was a great site that I found while looking at how to add a custom background via HTML. Not only did it have code that helped add a background with little alteration, but each line of code also had comments describing use. To show the entire background image, and keep the site’s footer at the bottom of the page, I utilized a clear PNG image file as a spaceholder. On the published site there is no trace of this image, and it creates the clean homepage look I was going for.
My goal for my site setup process was to not only have a good looking site, but also a template that I know how to edit and can build upon throughout the course. From my work on this first setup, I’ve found many good recourses talked about above I can go back to when I need guidance, and I’ve begun to feel comfortable with the simple commands of Markdown. I’ve learned that there’s not just one way to do things in this documentation and that you can usually work around problems you’ve had to come up with a solution. One such workaround I followed involved issues I was having with image formatting on my site. Not only were my images too large, but I was also running into issues with the Markdown code I was using to implement pictures. Conveniently enough, HTML can take out both of these issues relatively simply, using these lines of code shown below, I was able to attach an image to my page, as well as adjust the image size.
<figure>
<img src="../images/clear.png" width="500" />
</figure>
One final thing that I found incredibly useful while setting up and customizing my site, was the ability to look at Fab Academy documentation sites from previous years. Looking at these sites sparked some of my layout ideas, and also gave me some context on what goes where. Although I looked at many of these sites, I found myself going back to one of my instructor’s sites, Dr. David Taylor. Although his site was written in HTML, different than my Markdown-based site, It was a huge help when trying to find what goes where. The current content of this page referring to this site setup was originally written on my 0.5. Student bootcamp page, and it was after reading Dr.Taylor’s site I realized it belonged on this page.
Site Publishing¶
Due to my commitment to locally editing my site before pushing it publicly, publishing my site so it is visible to others involves pushing the code back to the GitLab, where the site is published usingGitLab CL. Thanks to some good documentation on the Fab Academy GIT Simple Cheat Sheet, I found these three lines to work, pushing the code back to the GitLab, and thus updating the public site.
git add . // stages all new changes made to your site
git commit -m "Updated Site" // gives your push a title that will be visible on GitLab
git push //pushes changes to your GitLab - when prompted, enter your SSH passphrase
Final Project Concept¶
I’ve always had an interest in having my own home garden capable of growing plants and herbs, as I enjoy the access to fresh foods, however, my past attempts at gardening always seemed to be relatively fruitless. Due to my structured highschool student schedule, I am usually not around to look after and take care of a garden, and thus, this want for fresh foods hasn’t become a reality. For my Fab Academy, I want to aim to fix my issue, by removing the time-consuming part of gardening, the growing of the plant itself. I’m aiming to create an automated window-sill garden, that can take measurements of soil moisture, rain/humidity, and temperature, compare the found values to a threshold, and water the plants accordingly. In addition to that, I think it would be great if all this collected data was output in a readable format for a user, so although they may not be able to be there when the plant needs to be watered, they still can check up on their garden. While researching for my final project idea, I stumbled across countless other ideas like this, many helping me form my goals for this project. Here are some links that I found helpful or influential to my idea Gardening + Arduino, Garduino, DIY Home Assistant Garden Automation System, Raspberry Pi Powered IOT Garden, and the Advanced Irrigation System. Although looking at projects like these gave me some inspiration, I have many personal design factors that have also helped me form my idea. For example, many gardens take advantage of red and blue lights to optimize plant growth, however, after settling on a window box form factor, the light pollution caused by these lights, would not outweigh the benefits of having them. In addition to that, I settled on a windowsill box, that way I could hang this garden outside of my bedroom window, and conveniently enough, this window is in direct sunlight most of the day, so there would be no need for additional lights.
Assignments to Devote Towards my Final Project¶
| Week | Tool/Pratice | Product | Notes | Link to Compleation |
|---|---|---|---|---|
| 2 | CAD | Window-sill box Model | ✔️ CAD | |
| 3 | CNC Milling | Window-sill box | ❌ | |
| 5 | 3D Printing | Cable managment, sensor mounts, mounting for irrigation pipes | ❌ | |
| 6 | Mirco Controller | Overall system controll | ❌ | |
| 7 | Laser Cutting | Acrylic fronts for gardens side boxes | ❌ | |
| 10 | Inputs | Water level sensor, temp, soil moisture, and humidity sensors | ❌ | |
| 11 | Moulding & Casting | Garden side boxes | ❌ | |
| 12 | Output | Water pump | ❌ | |
| 14 | Interface & Application | Readable output from gardens sensors | ❌ |
Final Project Sketches & Planning¶
In preparation for the following weeks of class and my final project, I spent a little bit of time planning through my ideas and goals for a final project shown in the images below. None of these ideas have been set in stone, and I’m excited to see how my project goals may change over time as the course runs. This process has already started to happen, shown in the images below, I’ve started to go through different iterations of goals for my final project code. After talking about final projects with one of my software-oriented classmates, Drew Griggs, I was able to better specify some goals for my code. In addition to this planning, I sketched out some concepts for my final project, that I will base my CAD designs on next week. I was greatly inspired by the ‘Farmhouse’ design style when sketching the windowsill box itself, this is one of the styles I appreciate the most and I tend to consider it when planning aesthetically. An example of another place I’ve used this style is on my Remote Learning Desk Project talked about on my About Me page.
