1. Principles and practices¶
This week I worked on defining my final project idea and started to getting used to the documentation process. Throughout the whole process of setting up my Git, mkdocs, and using windows powershell, I have been very confused, but have simultaneously learned a lot. Originally, I tried to follow along Adrian Tores’ documentation to set up everything, and it certainly helped me get things started, but when what it said would not work for me, I was far too confused to figure out what to do; I was often too confused to even know what question to ask. Big thanks to Richard Shan, who had a lot more experience using git and command terminals than everybody else at the lab, and Evan Park who, due to not having a laptop to work on until later in the week, invested time into gaining a comprehensive knowledge on the relevant topics before doing anything, both of whom helped me get through a lot of this week’s process.
SSH Code¶
First, I used Adrian’s documentation to help me identify myself, generate an SSH key, and put it into Git. I originally used Git Bash as Adrian recommended, but Richard put me on Windows Powershell. I ran the below lines of code for the first few steps:
Identification and SSH key code¶
git config –-global user.name “26vaughd@charlottelatin.org”
git config -–global user.email “26vaughd@charlottelatin.org”
cat ~/.ssh/id_rsa.pub
ssh-keygen -t rsa -C “26vaughd@charlottelatin.org”
Putting Code in Git Website¶
After copying the code it gave me, I navigated to my Git page as shown below:
I then clicked the profile icon in the top left corner with the profile picture, went to edit my profile>SSH Keys>Add new key (follow steps shown in image), and pasted the key I had copied into there.
Installing Python¶
Next I had to install python and mkdocs. Originally, I just used Google to search for a Python installer, on which I clicked install on the latest version. Later, I thought that Richard had used pip install python to install python on my computer. I used pip install mkdocs to download mkdocs. I then ran mkdocs new david-vaughn to create a new mkdocs file under the file “david-vaughn”. However, it came up with the error “The term ‘mkdocs’ is not recognized as the name of a cmdlet, function, script file, or operable program”. Richard again helped me to fix this by adding the python scripts folder to the System Environment Variables by going to System Properties>Advanced>Environment Variables>Path>New. For a while, though, even Richard couldn’t figure out what the problem was, as it was still showing up with errors. Eventually, he realized that I had installed the Python downloader online, but had never actually run it to install Python, and neither of us had commenced pip install python. After installing Python, everything worked out fine. Using mkdocs serve, I could then test to make sure mkdocs was working fine.
Cloning Repository¶
Now I had to clone the repository. After going to my git.fabcloud.org site, I took the existing repository, clicked “Code”, copied the URL given under “Clone with SSH”, went to Windows Powershell, then navigated to my “fab” folder (a folder I had created) in my files using cd fab. I proceeded to paste the URL in after typing the command git clone, so that my command looked like git clone git@gitlab.fabcloud.org:academany/fabacademy/2024/labs/charlotte/students/david-vaughn.git. This then cloned the repository into a folder it created name “david-vaughn” which was under the folder “fab”.
Committing and Pushing¶
After I was confident I had fully set up my documentation correctly in mkdocs, I could run my first commit and push. To do this, I used the three commands shown below. For the git commit -m "commit name", I named my first commit “test”, so it looked like git commit -m "test".
git add --all¶
git commit -m "commit name"¶
git push¶
Setting up theme¶
As I felt compelled to complete something beyond the necessary tasks, I decided to attempt to change the visual aspect of my documentation website, the theme. With the repository given to us, the theme is automatically set to “mkdocs”, which is fairly boring. At first, I changed it to the other theme given, readthedocs, by simply changing “theme: mkdocs” in the mkdocs.yml file to “theme: readthedocs”. This theme also proved unexicting, however, so I researched how to use a different theme. I found a website from which one can get the simple commands to run on Windows Powershell in order to download a theme. I began installing some and using mkdocs serve after adding them to my mkdocs.yml file so as to test them out. Some of these were still bland, but others looked much nicer. I eventually settled briefly on “simple-blog”, which worked fine when running mkdocs serve. However, much later in the week, when trying to commit and push, I would run git add --all, git commit -m "commit name", and git push.
But then there would be a pipeline error in the commit.
And it would say that this was not one of the available installed themes.
I decided not to bother too much more with it because I was already behind, but I installed and set the theme to “material”, what I considered the most aesthetically pleasing of the three available. That is what it likely is now.
Adam Stone’s Image Resizer and Fab Academy Networking Map¶
Adam Stone, a Fab Academy graduate from last year and fellow student at Charlotte Latin two years older than me, created two very useful programs, both of which I have taken advantage of. The first one is an image resizer which is helpful in saving data. To install it, I followed the instructions he layed out on his page here. Then, all I had to do was click “Resize Image”, select the photos from my files I wanted to resize, then select the folder in which I want to store the resized photos in. I have used it on all of my images in this documentation. The other program, the Fab Academy Networking Map, can be accessed here. It basically shows the most referenced Fab Academy pages for a given week.
Final Project Outline¶
I want to replicate and build on the table shown in this tutorial. Basically, the table holds sand, and in the sand is a metal ball. This ball is pulled by a magnet on a 2D axis system below the sand. To build on it, I wish to implement a design originally created by Neil Gershenfeld called an Urumbu. I also wanted to create a manual input system where the user could control the magnet. If possible, I also want to have it take an .SVG file and print it in the sand in the same way a vinyl cutter or laser cutter might.A sketched outline of what I want my final project to be is shown in the image below.
Week Summary¶
Throughout this whole first week, I was simply completely confused. Being new to Windows, never having even heard of a command terminal, markdown, vscode, git, mkdocs, a repository, a .yml, and having what seemed to be minimal knowledge on anything that came up this week, half the time, I was clueless on what I was even supposed to be doing, much less which of those aforementioned would be the next step. Because of this, I often hurt the process more than helped it, to which I again thank Richard Shan and Evan Park for basically getting me through this first week. One night, I had spent around 3 hours trying to figure out the next step in the process, in which I completely messed up my file system and subsequently ruined my progress. The next day, because we both now knew much more, in the span of only about 5 minutes, Evan helped me completely reset and build back up a solid foundation. Such a simple task can seem endless when I struggled finding the direction which I needed to go. Although I believe some parts of this week, I was too confused to actually learn anything, much of this struggle was necessary as I now understand and could replicate this whole process much better.