Skip to content

1. Project management

Fab Academy Assignment #1 📚

  1. Make a website and described how you I did it.
  2. Created an about me section describing myself.
  3. Include a sketch of your final project
  4. Signed and uploaded Student Agreement.

Previous experience

Prior to FabAcademy I had 0 experience in building websites. A few weeks before starting I thought it would be a good idea to get to grips with the basics. I found a couple of open source site, the first is called FreeCodeCamp.org where you can study web development for free. Their responsive web design course teaches all about HTML and CSS and I should donate to those guys for giving me a basis to start with. After picking up some of the basics, I found a site called w3schools.com There you can search for and learn various types of code, take tutorials and like freecodecamp, there are certificates to be earned with your learning progression.

Command line

So what is it?

The Terminal is a program included with all versions of Mac OS and resides in the Utilities folder. The Terminal grants us access to the command line. If our computers were ships, the command line grants us access to the captain's seat.

From this position of power we can tell our computer to do exactly as it's told through a text based interface.

## But Why???

There are several advantages to bossing your computer around through the command line over apps. It's free, it's fast, it's more thorough, it debugs and tells you about errors. You cut out the middle man and go directly to your computer's control center.

Here are some commands that I have been using so far...

Home Brew

One of the first things I did in the terminal was to download Home brew

Homebrew is a free and open-source software package management system that simplifies the installation of software on Apple's operating system, macOS, as well as Linux. This is especially useful for Mac users because a lot of the tools we will be using over the course of the fab academy, are not in the app store. Once you have home brew installed, you can just simple use the command brew install + [App/software you want], then watch as brew finds and downloads said program. To install Home brew, just visit their homepage and copy and paste the code into terminal.

"homebrew install"

Version control

What is Git?

Git is a Version Control System that keeps a history of changes we make on projects. We can have the files in a single server - centralized or distributed (when the files are distributed by servers). Many contributors can be working at the same time on the same project (Git will tell us if there is a conflict with the files). The idea is that we have the same files on the computer as on the system. We can also create branches (duplicate and change the work without conflicting with the master branch). We work locally on our computer and when we are ready we can upload our changes (push) or if we need to update our local files with the server ones, we can pull the files.

GitLab

At Fab Academy we use GitLab. GitLab is an open-source repository, it provides free open repositories (what we use) and private ones too. It is focused on providing features for developers where projects can be collaborated on and submitted. The repository can either be via the Gitlab site, but we can clone the repository to our local computers and edit documentation from there. Once we're done working locally we can push the edited version back to Gitlab where it is reviewed before either a successful pipeline completion or an error where changes have to be made.

SSH For Gitlab

Before you can clone your repository, you will need SSH key pairs, one public (the one you will be using to do your work on Gitlab) and one private key, that you do not want to share. First I checked if I already had an SSH key by typing the command -> cd ~/. ssh/ into the command line. I did not have the keys, so the next step was to generate an ssh key pair, the command for that is ssh-keygen -t ed25519 -C"your_email@example.com", with my email in exchange of the example.

How to clone?

You can clone your repository by pasting your Gitlab URL after the command Git clone . First visit your gitlab home page, where it says code in blue, open. Then there are two options, select SSH and copy to clipboard. Then enter -> Git clone git@gitlab.fabcloud.org:academy/fabacademy/2024/labs/waag/students/joe-wallace.git

Web Development

With only a small amount of knowledge on HTML and CSS, I have chosen MKDoc for my documentation. MkDocs is a fast, 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.

Python

MkDocs is written in python and you will be required to download that first to enable you to download MkDocs. I had some issue with my command line when trying to see if I had a version of python downloaded, so now I have two :P. To get the latest version of python you can visit their home page here but you should check if you have a version installed.

With Python installed, you can then work through the documentation on setting up your MkDocs website.

  1. Install MkDocs

    In The command line type ->pip install mkdocs

  2. Check you have it installed

    I struggled to get some commands to work, and had to do more research into the MkDoc commands. So, because I had two versions installed I had to give the command with the version as ->python3 -m mkdocs

  3. Create a new directory

    Then I could make a new directory, I called it fa2024 and used this command ->python3 -m mkdocs new fa2024

  4. Start the server

    Once the new directory was created I navigated to it using command ->cd fa2024 Then I gave the Serve command ->python3 -m mkdocs serve After loading this gave me a local URL INFO - [16:40:45] Serving on http://127.0.0.1:8000/ From here I could view the webpage and start to make changes and uploading content from my local fa2024 directory.

In the mkdocs.yml file is where you can change the page title and theme.

Then in the Docs folder I could create new documents, like "about me" for example, that contain their own Markdown files, these files will appear as pages on my website.

I have been using some of the following syntax's to edit my markdown files.

Visual studio code

Visual studio code is a code editor developed by Microsoft, designed for developers to write, edit and debug code across various programming languages. I have been utilizing VS code for editing code and documentation in my Gitlab repository. Once changes are made and saved, you will notice the pages in the top right hand corner indicate the changes, you can then select the commit button to push your work to Gitlab, Gitlab will see the changes and review them. It is important to give your commit a title, so you can keep a track of changes made, this is especially important if you are collaborating on a project. If the code passes inspection you can then pull from the Gitlab repository via the sync button. This would also be the case if you or a team member were to make changes to a document, you would first sync you VS code to get the latest version from Gitlab.

Publishing the website

I first moved repository to a new folder so that a clone wouldn't remove my local work. Using the commands -> mv fa2024 fa2024_bk

I then made a clone of the repository and put it into fa2024 folder. Removed public folder that I didn't need. Checked Git status. Git commit. Git Push.

Installed ncdu and checked the size of my repository. It was less than 10MB so good to go. I then gave the serve command python3 -m mkdocs serve

That didn't change anything because I didn't have a .yml file. I knew other students were using MKdocs, so I could copy their .yml file from Gitlab.

That code failed to pass as I was missing requirements.txt file. That file was also in the Gitlab of a fellow student, thanks Leo So I then copied the file content from Leo, created a new file in the fa2024 repository and pasted the code.

Reflection

What I've learnt in this week is that time is precious and that you need to walk before you can run. I thought I could just jump into building a website from a template site and that would be easy after grasping some HTML, I was wrong. Template sites are great tools, but you need a deeper understanding of the code they use and how they format the template. I also had issues because some templates are not maintained so can be buggy. So...For the meantime I am going to continue with Mkdocs as it more than satisfactory for documenting my progress and it's quite simple to navigate.