2. Project management¶
Setting up Gitlab and Mkdocs¶
I set up my ssh key with git lab and cloned my repo with instruction from these slides and the website of fab graduate Teddy Warner. I generated an ssh key on the command line making sure to run it as an administrator using the following command:
ssh-keygen -t ed25519 -C "23pana@charlottelatin.org"
It asked me for a file input, and I just pressed enter to have it use the default, and it asked me also for a password, and I typed one in.
I then opened gitbash as an adminastrator and typed in the following command to copy the ssh key to my clipboard:
cat ~/.ssh/id_ed25519.pub | clip
At first I had tried to run it on the command line, but I got an error.
Using this, I went onto gitlab and going to preferences then the ssh key section, I pasted my ssh key in. I then clicked the clone repo menu on my repo and copied the clone by ssh option, and I used the following command on the command line:
git clone [insert copied text on clipboard]
I then tested if it was working by changing the text in one of the docs slightly and running the following commands:
git add .
git commit -m "testing update"
git push
I downloaded mkdocs and launched my site with instruction from the same resources as above. First I downloaded the latest version of python from their website. I then ran some commands to make sure I had python working:
As you can see, it was running an old version of python I had installed, so I uninstalled it, and that is when I ran the command again to get the result of python 3.7 above, so I proceeded to uninstall all old versions of python on my PC. That worked and I was able to use python 3.10, but when I tried to install mkdocs with the following command it threw an error:
I tried uninstalling python then reinstalling, but that did not work. Then, with the advice of my classmate Jack, I ran the same command while running the command line as an administrator, and that worked.
To complete the process, I ran the following commands to install necessary plugins:
pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
I then tested mkdocs with the following command:
mkdocs serve
Visual Studio Code¶
For my text editor, I decided to use Visual Studio Code. I had already been using it prior to fab, and I like that at its base level, it is a text editor without its own build tools, but it can be made quite powerful with different extensions to increase the ease of coding.
Some of the extensions I have installed are:
- Error Lens to have more detailed and noticeable error highlighing
- Material Icon Theme to give icons to different file types, making them more easily distinguishable
- Monokai++ just to have a syntax highlighting scheme I find pleasing
- Tabnine for AI powered tab complete
- Also language support for different languages I may use like python and c++
Documentation with Mkdocs and Gitlab¶
To gain a better understanding of git, I watched this video.
I learned to use git status to be able to view the status of any changes and if they have been added. git log can be used to see a history of commits, and git checkout can be used to revert to a previous commit or go to a different branch. git branch can either view the different branches or create a new branch if given a branch name, and git merge merges branches together.
I had little trouble writing my about me and pasting in the studnet agreement, but I did have some issues with using videos and pushing to gitlab.
I had a local file of previous work that I wanted to put in my about me, and I used this site to see how to put in videos. I ran the following command:
pip install mkdocs-video
I then went onto the mkdocs.yml file and added mkdocs-video to the plugins, and I used the following line to insert the video in:
Rather than inserting the video in, it had the video file download to my computer
I then converted the video file to an mp4, and that worked, but when I went to push to gitlab it ran the following error:
I tried compressing the video file and cutting it down, but I couldn’t get the size small enough. Then I asked Teddy Warner for advice, and he suggested that I upload the video to youtube and embed it from there, and that worked.
After updating my week 0 page, I went to push to gitlab, but the commit was too large, so I split the commit into smaller commits, and I found that each push could handle 2-3 image files at a time.
After I had fully committed, I recieved emails saying that a job in gitlab failed. I checked and saw that all my files were updated, so it couldn’t be an upload error. I then checked my site on the fab academy page and realized that it had not updated, so it was an issue in deploying. I then thought back to me adding the mkdocs-video plugin to the mkdocs.yml file and thought that that could be messing up the deployment since that plugin may not be installed or recognized. Since I was now embedding the videos with youtube, I no longer needed the plugin, so I deleted it and pushed again, and it was resolved.
Later, I was talking to a previous fab graduate, Charles De Mey, and he saw the size of my image files, and he recommended that I compress them, so I installed ImageMagick Display. To use it I opened it and selected file > open and selected a file. Then I selected view > resize and used 500 x 500 for each image with little variation and exception.
With the advice of my global instructor, Yuichi Tamiya, I tried embedding a video directly with an mp4 in the repo. I installed ffmpeg and added it to my path environment variable. Referencing this documentation, I removed the audio of a video with the following command:
ffmpeg -i cornerBeforeLeveling.mp4 -vcodec libx264 -b:v 1000k -vf scale=-2:1080 -an cornerBeforeLeveling2.mp4
I then looked at this site to compress further with the following command:
ffmpeg -i cornerBeforeLeveling2.mp4 -vcodec libx264 -crf 32 cornerBeforeLeveling3.mp4
Referencing this documentation once again, I embedded the video, which also appears on my week 0 documentation.
I ended up deciding to stick with embedding youtube videos for long videos (greater than 1 minute) both to reduce repo size and to have a more public platform displaying my work.