1. Principles and practices¶

This week I worked on defining my final project idea and started to getting used to the documentation process. I also worked on installing git and settting up repositories, mkdocs, and learning how to use Gitlab.

References:¶

Adrian Torres’s Documentation
Adam Stone’s Image Resizer and Documentation

Initial Setup - Git¶

The first step in the process was to install Git. I used the Git Simple Cheat Sheet to accomplish this. Then, I had to login to my assigned GitHub account. After I received several emails explaining what groups/classes I had been put in to, I received one that gave me access to my GitLab account and my repository (or repo). Once I had my git repository, I first had to create an SSH key. To do this, I used these commands:

git config –-global user.name "landon-broadwell"
git config --global user.email "26broadl@charlottelatin.org"
cat ~/.ssh/id_rsa.pub

This set the global username to the one associated with my GitLab account, gave Powershell an email address to send the SSH key confirmation to, and created the key. After the final command, I pressed the Enter key a few times and got my SSH key.

The reason that I needed this key was to have permission to clone my GitLab repository locally and be able to properly edit it. I pasted the provided SSH key into the “SSH Key” section of my profile settings and went to clone my repo. I went to the main page of my repo in GitLab, selected the “Code” bar, and copied the link file name shown there.

Once I had this, I ran the following command in Powershell:

git clone git@gitlab.fabcloud.org:academany/fabacademy/2024/labs/charlotte/students/landon-broadwell.git

Now that I had cloned my repository, I opened it up in Visual Studio Code (VSCode), which I had already installed months prior. This was the current hierarchy of files:

The hierarchy of the files.

However, I wanted to not have to code everything in HTML, a language that I am not familiar with. In order to avoid this, I took the route of using Mkdocs as an alternative.

Installing Mkdocs¶

Before installing mkdocs, I had to install python here. When doing so, I made a mistake by not selecting the “Add python to environment variables” option, which caused complications later. I then installed mkdocs, with the additional help of this guide, and ran it to check if it had installed properly with:

pip install mkdocs
mkdocs

However, I recieved an error that said

mkdocs : The term ‘mkdocs’ is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again

I continued to run the “mkdocs” command across various folders and my directory, but nothing worked. With the assistance of Richard Shan, I discovered that the issue was with 1. the scripts folder associated with python 2. python not being an environment variable. By going to Advanced System Settings in my computer, I was able to add python to PATH and make it an environment variable. Then, I went to the Scripts folder and moved python into there, even though it normally is meant to be in the first place. I reran “mkdocs” and it had successfully installed.

Setting Up the Website¶

I discovered from the other students that the best way to set up my website was through the Fab Academy Student Template. From here, I copied the “docs” folder, the mkdocs.yml file, and the requirements.txt file and placed them all into my repo. I then copied the .gitlab-ci.yml file and pasted it over my previous .gitlab-cit.yml file, as the previous one was outdated. My folder now looked like this:

Now that I had all of these parts of my repository set up, I was finally able to begin work on creating and designing my website. This first thing I did was push this new data onto the website to see if it had worked.

git add . 
git commit -m "COMMIT MESSAGE"
git push

I suspect part of the reason that this push went through without any errors was becaue of the streamlining of part of it through turning many parts of the mkdocs.yml file into comments. Nonetheless, it worked and I was officially able to start properly documenting.

Reflection¶

This week was very rough, but thanks to the help of my friends and others’ documentation, I was able to successfully get through it. I learned many things about how files worked and the basics of documentation. My largest struggle was just starting, as I was unsure of how I could really start, but once I got a decent foothold, I was able to carry momentum until the end of this assignment.