1. Principles, Practices, and Project Management¶
This week I set up my website - the one you are reading on now! Additionally, I started working on final project ideas.
Git and Python¶
First, I downloaded git at https://git-scm.com/downloads and python at https://www.python.org/downloads/.
-
Git is “Git is a distributed version control system that tracks versions of files” ([source(https://en.wikipedia.org/wiki/Git)]).
-
Gitlab is “GitLab is a web-based Git repository that provides free open and private repositories, issue-following capabilities, and wikis. It is a complete DevOps platform that enables professionals to perform all the tasks in a project—from project planning and source code management to monitoring and security” (source); “GitLab offers a location for online code storage and capabilities for issue tracking and CI/CD. The repository enables hosting different development chains and versions, and allows users to inspect previous code and roll back to it in the event of unforeseen problems” (source).
Git Commands¶
The main git commands I use to upload files to the remote repository are git add, git commit, and git push.
-
The
git addcommand “adds a change in the working directory to the staging area. It tells Git that you want to include updates to a particular file in the next commit” (source). -
The
git commitcommand “captures a snapshot of the project’s currently staged changes. Committed snapshots can be thought of as “safe” versions of a project—Git will never change them unless you explicitly ask it to” (source). -
The
git pushcommand “The git push command is used to upload local repository content to a remote repository. Pushing is how you transfer commits from your local repository to a remote repo. It’s the counterpart to git fetch, but whereas fetching imports commits to local branches, pushing exports commits to remote branches” (source).
Repo Folder¶
I created a new folder by clicking control click and selecting ‘New Folder.’ I named the folder fab-alana. I then control clicked the folder and selected ‘New Terminal at Folder.’
To clone my repository: from my gitlab website, I clicked the “code” button and selected “Visual Studio Code (SSH)”. I then clicked allow, selected the folder “fab-alana” as the repository located, and then opened the folder in Visual Studio Code.
Mkdocs and Visual Studio Code¶
I downloaded Mkdocs at https://www.mkdocs.org/.
- Mkdocs is a “static site generator designed for building project documentation. It is written in Python, and also used in other environments” (source); “MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file” (source).
In my terminal I then ran pip3 install mkdocs
Next, I cloned my repo by typing mkdocs new fab-alana in the terminal. This put a mkdocs.yml file into the clone folder, allowing me to work in Visual Studio Code with mkdocs.
Once in Visual Studio Code, I was able to open the mkdocs.yml file and edit the template colors, text style, etc.
for example, I changed the theme color as follows:
theme:
name: material
palette:
primary: cyan
accent: blue grey
Pip¶
In my terminal I ran
python -m ensurepip
to download pip.
SSH Key¶
- SSH key pairs “offer a more secure way of logging into your server than a password that can easily be cracked with a dictionary and brute force attacks” (source). “An SSH key is an access credential for the SSH (secure shell) network protocol. This authenticated and encrypted secure network protocol is used for remote communication between machines on an unsecured open network. SSH is used for remote file transfer, network management, and remote operating system access” (source).
In my terminal I ran
git config --global user.email "25duffya@charlottelatin.org"
ssh-keygen -t -C "25duffya@charlottelatin.org"
I then specified the folder where I wanted the SSH key - I clicked enter to specify no folder. I then entered a password that I have to enter each time I want to push. I then saved my SSH key.
Next, I uploaded my SSH key into git and saved it. This will now allow me to push!
Template¶
The template I used can be found at this link: https://gitlab.fabcloud.org/fibasile/fabacademy-student-template/-/tree/master. First, I downloaded the template as a zip file. I then double clicked the file to extract its contents into my repo folder. Next, I deleted the html template and public folders already in my repo - these folders will be replaced by the new template.
In my terminal I then typed mkdocs serve. I then committed the changes by saving the folder, designating a commit message, saving the file again, and typing
git add .
git commit -m "name of commit"
git push
and then entering my password that I designated earlier with the SSH key.
Markdown¶
In VSC, I use Markdown.
From The Markdown Guide, “Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents.
When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different. For example, to denote a heading, you add a number sign before it (e.g., # Heading One). Or to make a phrase bold, you add two asterisks before and after it (e.g., this text is bold). …Markdown syntax is designed to be readable and unobtrusive.”
Compared to other languages, such as HTML:
“Markdown is easier to write than HTML, and it’s easier for most humans to read Markdown source than HTML source. However, HTML is more expressive (particularly regarding semantic tagging) and can achieve some specific effects that might be difficult or impossible in Markdown.” (source: Google Article)
I like to think of it best as Medium puts it, “Markdown was not intended to replace HTML, but to augment it — it is meant as a writing tool, whereas HTML is a publishing format. …The idea was to make it very easy to read, write, and edit prose with some formatting, and that the result should be usable as-is.”
Adam Stone’s Image Resizer¶
To install Fab Academy 2023 Alumni Adam Stone’s image resizer, I clicked this link. I then opened its folder from my downloads. A few changes need to be made before this can run. Open the requirements.txt folder and, depending on your python version, change 9.4.0 to said version, for me this was 10.2.0. I then saved the file, clicked resize.cmd, and in the terminal ran
python3
python3 -m pip install pillow
python3 main.pym
to run the image resizer.
Reflection¶
My first week of Fab Academy was a very cool, nerve-wracking experience. I learned so many things that I had no idea my computer could do - like terminals - and learned how to make my own website! It was very frustrating at times, but the end result is definitely worth it. The biggest lesson I learned this week was to rely on friends and help them when I can :)
Helpful Tools¶
For image compression: Optimizilla
For Mac image conversion: CloudConvert
Reflection¶
This week absolutely sucked. Using my hindsight of writing this reflection after I finished all of my other weeks, this was hands down the worst week. It’s so confusing trying to set up a website and there’s no way to go about it besides just trying. You’re bound to screw some things up in the process and probably shed a few tears, but after the fact, it’s really fun to customize your website and make it your own!
References¶
Dariyah Strachan 2024 Fab Academy
https://squidfunk.github.io/mkdocs-material/customization/
https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write
https://squidfunk.github.io/mkdocs-material/setup/