2. Project management

This week I worked on defining my final project idea and started to getting used to the documentation process.

Individual Assignment:

• Build a personal site describing you and your final project.

• Upload it to the class archive.

• Work through a git tutorial.

Starting the Project

First, I log into the Fab cloud on Gitlab using the credentials used to enroll into FabAcademy. You will already have a project created for you by FabAcademy. To link the account to your pc, you must configure it using the two following commands in your terminal one at a time:

git config --global user.name "John Doe"

git config --global user.email johndoe@example.com

SSH Key

Next you must generate an ssh key so you can be authorized to send files to your repository without having to enter your password everytime.

First check if you have any already, to do so, open your terminal and enter the following command:

$ ls -al ~/.ssh

If you don’t have an ssh key, you generate one using the following command in your terminal:

$ ssh-keygen -t ed25519 -C "your_email@example.com"

You’ll be prompted to “Enter a file in which to save the key,” act accordingly and then when asked to type a secure passphrase, you can simply press enter on your keyboard in case you don’t want one.

Next, you will have to configure your gitlab to use your ssh key. Copy the ssh key to your clipboard and then on gitlab, click on your avatar> preferences > ssh keys and paste it under the “key”. Set a date of expiry to some date that is very far so it never expires, and then add key.

Then, clone your project to a folder on your desktop using ssh key by running the following command in your terminal:

$ git clone (paste url here without brackets)

Now you will be able to upload files to your repository using your local one easily.

Mkdocs

For the website language (I think that’s what it’s called) there are many options to choose from listed on the FabAcademy website. Personally, I chose Mkdocs since it uses the markdown language which is relatively easy to use; also, it has a very minimal and sleek design which I enjoy.

To use mkdocs, you should already have installed pyhton, as well as pip, the package manager for pyhton. To check, you can run the following:

$ python --version $ pip --version

If you don’t have any, you can install online from Python.org. As for pip, if you’re using a recent version of Python, the Python package manager, pip, is most likely installed by default. However, you may need to upgrade pip to the lasted version:

pip install --upgrade pip

If you need to install pip for the first time, use the following link.

Next you will need to install mkdocs using the following command in your terminal:

pip install mkdocs

Then, install the material for mkdocs using

pip install mkdocs-material

The repository installed preset files that acted as a template for my portofolio which was awesome!

The Text editor

To document your work, you’ll need a text editor to edi the files. I installed brackets to act as the text editor and learned the basics of the markdown language to start editing my files. There are many other text editors but I chose to use brackets because it is very easy and comfortable.

Although I haven’t changed much with the template, you might notice that the nav bar is in white rather than a deep indigo. I changed the primary color in the theme section of the code in mkdocs.yml file.

Markdown

The language being used for documentation with mkdocs is Markdown. I learned it off the markdown tutorial link under the “Useful Links” section of this page.

The basics though are as following:

To add text: just start typing!

To add a title: add a ‘#’ before the title and then one space using the spacebar. The more hashes you add before the title, the smaller it becomes.

To make your text in bold: add two astericks before and after your text enclosing it in a asterick socket.

To italicize: add an underscore ‘_’ before and after the text.

To add a picture: copy the following format, and change the code to fit your picture’s location.

![Alt text](../images/Picturename.format(jpg,png,etc.))

Make sure to first compress the size of your images as there is a maximum amount of data that could be pushed to the cloud. I personally do that through uploading them to Facebook then downloading them off of the website.

To add code: enclose your code with backticks.

There are many other cool things you could do with markdown, and they are all relatively easy, which is why I chose to use markdown.

Git Commands

To get a live preview of what your site looks like, you can use the following command and then paste the https link onto your browser.

$ mkdocs serve

To upload the files to the Fabcloud, or in simple terms: to make your changes visible to the public, you will need to run the following commnads:

After adding a file or making a change in the local repository, run git add . first.

Then git commit -m "Add a memo", adding a note will help you identify your commits and if changes need to be made, you will easily be able to navigate to the specific commit.

And finally, the last step is to git push, which from the command itself you can infer that it pushes your changes to the cloud, and locks everything in place.

Useful links

• FabAcademy - Tutorials
• Markdown Tutorial

Issues/ Solutions

• In my previous attempt at documentation, my files reached a whopping size of 192mb! Upon asking, I found out that the key was image optimization, so I now use ImageOptim before uploading any images. However the files were still too big, so I now upload them to Facebook, then download them and it comes of at a pretty impressive size - very small.

• Deadlines. I just forced myself to get things done, lol.