2. Project Management¶
This week, I became familiar with GitLab and created a student website introducing myself and my final project idea. My process is documented below.
Getting Started¶
Note: Since this was my first time using Git to document my work, I made the mistake of not logging screenshots as I worked. The screenshots referenced in this documentation were generated retroactively using a “dummy repository” rather than the repository I used to generate this site.
To save time in the long-run, I attempted to clone my repository from the GitLab archive so that I could work on it locally. Initially, I enabled the Linux Subsystem on Windows 10 and installed a Ubuntu terminal. I found the subsystem terminal to be confusing, especially since it was referencing Linux paths that were named differently in Windows. Ultimately, I decided to install a Ubuntu partition on my hardrive so that the terminal would be more consistent and easy to work with.
Once I got Ubuntu up and running, I installed Git with the following command line:
sudo apt-get install git
In class, it was mentioned that in order to push to the archive, we would need to generate an SSH private and public key. On GitLab > Settings > SSH Keys, there is a link to a tutorial for generating keys. Following this procedure in the command line, I ran:
ssh-keygen -t rsa -C “m.e.branc@gmail.com” -b 4096
This outputs both a public and private key; the public key needed to be copied and pasted into the “Key” dialogue box on GitLab > Settings > SSH Keys and added.
Cloning My GitLab Repo Locally¶
Once I had installed Git and added my SSH key, I was ready to attempt to clone my GitLab repository onto my machine. I searched for “cloning GitLab repository locally” and found a tutorial on GitLab Docs under “Command Line basic commands.” The tutorial recommended using an SSH protocol when copying the link to the GitLab repo, and stated that this was easier to use than HTTPS once it was set up (SSH setup completed in the “Getting Started” section). It showed how to choose the particular protocol from the dropdown menu to the left of the repo link on GitLab.
Following the tutorial, I cloned my GitLab repo onto my machine using the command line:
A folder was created in my present working directory that was named for the lowest-level directory in the GitLab repo link, in this case, the student’s name (madeleine-brancaccio). The folder structure follows the folder structure of the online repo.
Editing My Site¶
I used the tutorial at MkDocs.org to install and start editing my site using an MkDocs template. I installed MkDocs with the following command line:
sudo apt-get install mkdocs
MkDocs has a built-in dev-server that allows the developer to preview their work, identical to how the site would look when published. I used the following command line to get an initial sense of the how the site looked before I made any changes:
mkdocs serve
Unfortunately, I ran into an error related to the theme defined in the YAML:
When I googled this error, I found that the themes needed to be installed. Instead of installing the “material theme,” which was the default theme referenced in the YAML, I used the built-in mkdocs theme for simplicity. To do this, I replaced “material” with “mkdocs” next to “theme” in the YAML.
To figure out how to insert images into MkDocs, I referenced my images in the same way as other images were already referenced in the template, adjusting the path and image file name.
I then made sure to at least meet the assignment criteria of introducing myself and my final project, mostly just by replacing text in the template and without making any major structural changes for now. I consider this to be completing the first spiral in terms of task completion for this week.
Image Resizing¶
It did not occur to me until the Project Management Recitation that image resizing and compression should be performed before pushing to the class archive. This is because GitLab saves all iterations of a work that is pushed to the archive. Pushing changes does not overwrite previous versions, so if you initially pushed with a full-resolution image, that image will still be taking up space in memory even if you later push a compressed version of the image. In the future, I will be sure to compress images before pushing.
To learn about image resizing via the command line, I Google searched resizing with ImageMagick, which was brought up in class. I installed ImageMagick using the command line, and used the mogrify command to scale images:
sudo apt-get install imagemagick
As I continue to become familiar with GitLab, I plan to learn more about image compression in order to strike a balance between image quality and saving space on the archive. I also need to be more cognizant of backing up my original images in case I accidentally scale an image down too far.
Committing Changes and Pushing to the Class Archive¶
I used the GitLab Docs tutorial “Start using Git on the command line” as a guide for committing changes and pushing from my local repo to the class archive on GitLab. The tutorial recommends first displaying any changes to the files in your current working directory, which should be set to the highest directory in the local repo. This step is necessary before proceeding, since in order to save space you must be clear on what you are committing.
The command line below shows my process for checking, committing, and pushing changes:
During the commit, the command line prompts for a description of the changes, which helps you keep track of multiple revisions. Once the changes are committed, the repo is ready to be pushed:
Signing Fab Academy Student Agreement¶
Using the student agreement cloned into my local repository, I edited the document with my name to indicate that I agree to the terms of the class. I then committed the changes and pushed to the online repo.
Next Steps¶
Now that I have met the basic requirements for the assignment, I am interested in looking into alternative MkDocs templates and customizing them with my own design. I would like to continue to work on the structure of this site throughout the course to make it more expressive.
1/30/19. I installed the MkDocs Bootswatch theme and set my theme in the YAML to “flatly” for a nicer color scheme. I initially ran into issues installing new themes, but after Google searching the error, I found a forum on GitHub where someone ran into the same issue. They resolved it by uninstalling MkDocs (which they had originally installed with Homebrew) and reinstalling it with Pip. I had originally installed MkDocs will Apt, so I figured I might be in a similar situation. After removing MkDocs with Apt and reinstalling it with Pip, I was able to successfully use the Bootswatch themes. The command lines were as follows:
sudo apt remove mkdocs
sudo pip install mkdocs