Week 1. Principles and practices, Project management¶
Researching And First Steps¶
Today is January 22, and that means Fab Academy has started!!! I immediately began researching last year’s participants, specifically Areg Khalatyan’s and Elen Grigoryan’s documentation, as well as Rudolf Igityan’s and Maxime Richard’s from the year before. Then, I started exploring the Fab Academy site, particularly the “Tutorial” section. It became clear that the following softwares are needed for working on the site for documentation.
- Git For managing and uploading my Fab Academy documentation to the repository using Git commands.
- Visual Studio Code For writing, editing, and managing the code and Markdown files.
- Python For locally running a simple web server for debugging my website without the need for pushing and loading it on external servers.
Setting Up Git¶
What is Git? Why I need Git?
Git is a version control system that tracks changes in your files, helps manage your projects efficiently, and enables collaboration by syncing with remote repositories for GitLab.
This image was taken from an article on Wikimedia, which are free of charge to use.
I Need Git for:
- Manage Documentation: Tracking and updating my project documentation easily.
- Sync with GitLab: Pushing my files to the Fab Academy repository and keeping my work backed up.
After installing Git, I created a folder for all Fab Academy files and ran Git Bash.
I need to configure my local Git environment with the same details used on GitLab. I wrote these commands in Git Bash.
git config --global user.name "Your name"
git config --global user.mail "Yourmail@example.com"
To make sure all the parameters were saved, I entered this code.
git config --list
After realizing that I am making progress, I proceed to generate the SSH key and clone the repository 😆.
Generating SSH Key and Cloning Repository¶
I started researching what an SSH key is and realized that it is used for securely connecting to remote servers without needing a password each time.
I will generate the ED25519 SSH key because it is more secure and faster than the RSA key, and it is recommended for modern SSH connections.
ssh-keygen -t ed25519 -C "Comment"
Two files will be generated: “Key” and “Key.pub.” There are two ways to get the key: you can open “Key.pub” with a text editor (like Notepad) or run a command to copy the contents of “Key.pub” to the clipboard.
cat ~/.ssh/id_ed25519.pub | clip
Then I went to the GitLab website, typed “SSH” in the search bar, and found the section.
Then I paste the SSH key, and Voilà!
Git Commands, Setting up Visual Studio Code¶
Since I have already generated an SSH key, I will clone the repository using this method. I entered the Fab Academy project on GitLab and copied the link.
Git Commands¶
First, let me show you the Git Bash commands I will use throughout Fab Academy.
git clone
git clone "Your repository"
This command is used to obtain a repository from an existing URL.
git add
git add .
This command adds a file to the staging area.
git commit
git commit -m “[ Type in the commit message]”
This command records or snapshots the file permanently in the version history.
git status
git status
This command lists all the files that have to be committed.
git push
git push
This command sends the committed changes of master branch to your remote repository.
After learning Git commands, I started cloning my repository into the folder I created.
I decided to add a file test.txt using Git Bash to show how all the Git commands work and also to try making a push.
And Voilà!! As we can see, our file was successfully added to the repository!!
What Code I Will Use ?¶
I will use Markdown instead of HTML because it is much simpler and more user-friendly, making it easier to create clean and well-structured documentation without needing extensive coding knowledge. It allows me to focus on the content rather than spending time writing complex HTML tags, while still being powerful enough to include elements like images, links, and formatted text. Additionally, Markdown integrates seamlessly with GitLab, making it the ideal choice for managing and presenting my Fab Academy documentation efficiently.
But anyway, I will add CSS styles and some HTML tags to make my site more colorful and visually appealing with a better design.
There is a very good site for learning code, especially CSS and HTML. I will put the link here: W3Schools.
In Elen’s documentation, I found Julian’s template for MarkDown, which I downloaded and replaced in my project folder.
Setting Up Visual Studio Code And Mkdocs¶
Visual Studio Code¶
So, I downloaded and installed Visual Studio Code from this link.
After installation, I needed to open the project, which I did right away.
Mkdocs¶
MkDocs is a static site generator that’s geared towards project documentation. It allows you to create and host documentation websites easily, using Markdown for content and YAML for configuration. It’s a great tool for building user-friendly, customizable documentation sites with minimal effort.
I found the user guide for installing MkDocs at this link.
First, I installed Python. The documentation mentioned that I needed to install Pip, but during the installation, I noticed that pip was already being installed as part of the Python installer.
Pip is the package installer for Python.
It’s very important to check the box during installation for “Add Python to environment variables” so that you can run Python and pip commands from any terminal or command prompt without needing to specify the full path to their locations. This allows for easier access and usage of Python across your system.
After installing Python, I ran terminal in Visual Studio Code by clicking Terminal > New Terminal.
To make sure Python and pip are installed, I write these commands.
python --version //For checking Python.
And
pip --version //For checking Python.
If everything is okay, it should look like this.
After that, I started installing MkDocs and the Material theme using these commands:
pip install mkdocs //Installing MkDocs using Pip
Then
pip install mkdocs-material //Installing MkDocs Material using Pip
Then
pip install mkdocs-Git-revision-date-localized-plugin //Installing Plugin
To check if MkDocs is installed correctly, I write this command:
mkdocs --version
I got this, which is very good, it means that MkDocs is installed correctly.
Let’s run my website locally!!
This command will run MkDocs and my Site will be visible locally:
mkdocs serve
Using Ctrl + Click I open my page in Browser locally.
Coding¶
As I already said, I will use Markdown, HTML, and CSS.
Markdown¶
So, Elen helped me with all the questions, and she gave me a link for a detailed guide on customizing the mkdocs.yml file.
Except that, the file has comments that are very helpful for changing colors, fonts, etc.
Here I Changed font of my Web Site using Google Fonts link wrote by comment.
For example, I added a light and dark mode using the Material for MkDocs website by adding this code:
theme:
palette:
# Palette toggle for automatic mode
- media: "(prefers-color-scheme)"
toggle:
icon: material/brightness-auto
name: Switch to light mode
# Palette toggle for light mode
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
# Palette toggle for dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
toggle:
icon: material/brightness-4
name: Switch to system preference
By adding primary: orange, I changed the color of the bar to orange.
Html and CSS¶
It’s very convenient that you can add CSS to Markdown code at any time. Some example of CSS what I’m using in my code.
As you can see, I added CSS to the Markdown to position my photo on the left and the text on the right, giving the site a more beautiful appearance.
Result
Here are some HTML Tags what I’m using in my Codes:
<b>Text<b> - Making the “Text” bold.
<br> or <br></br> - Adding a new line.
Compressing Files¶
One of the most important things is that the total size of all photos and videos each week should be no more than 10MB. So, I decided to make a script to compress photos and stay under this limit. ChatGPT helped me with this.
So, for this, we need to install Pillow via pip.
pip install Pillow
After installing Pillow we need to make file. I named it compress_images.py.
Then I opened the file using Visual Studio Code and pasted the code that ChatGPT gave me:
import os
import shutil
from PIL import Image
def resize_image(image_path, target_size_kb):
temp_path = os.path.join(os.path.dirname(image_path), f"temp_{os.path.basename(image_path)}")
try:
with Image.open(image_path) as img:
img_format = img.format # Save the original format
max_size = img.size # Original image size
while os.path.getsize(image_path) > target_size_kb * 1024:
# Reduce the size, keeping the aspect ratio
new_size = (int(max_size[0] * 0.9), int(max_size[1] * 0.9))
img.thumbnail(new_size)
img.save(temp_path, format=img_format)
# Check the size of the temporary file
if os.path.getsize(temp_path) <= target_size_kb * 1024:
break
max_size = new_size
# Replace the original file with the resized one
os.remove(image_path)
shutil.move(temp_path, image_path)
except Exception as e:
print(f"Error resizing {image_path}: {e}")
finally:
# Remove the temporary file if it still exists
if os.path.exists(temp_path):
os.remove(temp_path)
def process_folder(folder_path, target_size_kb):
checked_folder = os.path.join(folder_path, 'checked')
os.makedirs(checked_folder, exist_ok=True)
for root, _, files in os.walk(folder_path):
for file in files:
file_path = os.path.join(root, file)
if file.lower().endswith(('jpg', 'jpeg', 'png', 'gif', 'bmp', 'tiff', 'webp')):
try:
# Resize the file if it's larger than the target size
if os.path.getsize(file_path) > target_size_kb * 1024:
resize_image(file_path, target_size_kb)
# Move the file to the 'checked' folder
shutil.move(file_path, os.path.join(checked_folder, file))
except Exception as e:
print(f"Error processing {file_path}: {e}")
if __name__ == "__main__":
folder_path = r'W:\Photos' # Folder path to be processed
if os.path.exists(folder_path):
process_folder(folder_path, 300) # 300 is size of compressing.
print(f'Processing completed. All images moved to {os.path.join(folder_path, "checked")}')
else:
print('The provided folder path does not exist.')
❗Don’t forget to change the directory where your photos are located so that the script works properly.!!
❗You can also change the value to adjust the file size, and I set it to 300 KB.
Everything is ready. Now we need to place the images in the folder and run the script using Git.
python compress_images.py
❗When you run the script, it will automatically create a folder called checked and move the images there, but already converted.
❗If an image is smaller than 300 KB, it will simply be moved to the folder without compressing.
As you can see, the images were quite large, but after compressing, they all became smaller than 300 KB.
Before:
After:
As you can see, it reduces both the resolution and the quality, but it’s not too bad. The main thing is that the servers won’t be heavily loaded. 👍
Using Artificial intelligence (AI)¶
In the Student’s Bootcamp 2025 - Fab Academy, I learned how to use AI correctly. This was very important for me because I use it a lot in my daily life. I also want to share that I use the regular version of ChatGPT to translate from Russian to English since my skills are not strong enough to write all the documentation correctly, especially when it comes to grammar. To avoid troubling my instructors with my poor English, I only use ChatGPT for translation purposes. Let me show you! 😊
Here’s what I found on the website, and I would like to share it with you because I think it’s very important!
- Honestly reporting on my work, and appropriately attributing the work of others (both human and machine, including AI prompts)
- When using AI, mention clearly which tool (which tool version also) an the prompt you use. Be clear on your production and AI production.
- Always credits when using other code, text, pictures, video, music, tutorials.
- Mentioning I found this picture on google is not enough. Minimum: original link, then the name of the author. Sometime date and version are important like article from Wikipedia. You can find more precise rules with bibliography rules.
I recommend everyone read the article about the proper use of AI in the Fab Academy courses!
List of Tools (Softwares) I Used This Week¶
Here i want to share you with Software List:
- Git , Python , Visual Studio Code.
- Snipping Tool (Windows), Paint (Windows)
- Code Spell Checker (Extension for Visual Studio Code)
Conclusion¶
Since I studied at TUMO , especially at 42 Yerevan, it was easy for me to use Git because all our projects were on GitHub. I also found it interesting to use Markdown because it makes writing documentation easier. But I want to say that it’s not as easy as it seems. Last year, I saw how Fab Academy students wrote their documentation, and it looked easy, but in reality, it’s not! 😊