Skip to content

2. Project management#

Topics this week: Syncrhonization, version control, web development, blogs, wikis, content management systems, videoconferencing, remote desktop, cloud computing, project management programs, and project management principles.

Assignments#

Build a personal site describing you and your final project
Work through a git tutorial

Building a personal site#

Commands I use for the command line:#

  • pwd: present working directory (aka folder). This will show you which folder you are in.
  • cd: change directory. You append this command with a file path, e.g. 'cd ~/Documents/' to navigate to the docs folder
  • ls -lah: list all files in this directory
  • .: this folder. For example, to open this folder in the finder, you can use open .
  • ..: the parent folder of this folder. You can use this to navigate up out of the folder you're in.
  • pbcopy < PATHTOFILE to copy the content of a file onto the clipboard
  • rm: remove file
  • rm -rf: delete directory and all it's contents (can't be undone)
  • sudo: prefix any command with sudo to override any permissions issues. Sudo enables you to take control and act as the root user. It is unwise to use this often. Use only when necessary, and consider reading more about why this can cause issues for your computer.
  • dir: create a directory
  • touch: create a file
  • mv: move or rename a file. first input is the original path, second input is the destination. 'mv documents/oldname documents/newname'

Setup Git#

Using terminal, check if you have git installed: git --version
If not, download it from this link and install it. Checkout the FabAcademy recitation on version control, linked at the end of this page

Generate a SSH-key#

Using SSH allows you to securely download and upload data. According to Wikipedia, SSH stands for Secure Shell and is defined as a cryptographic network protocol for operating network services securely over an unsecured network.

It only takes a few steps to set up:
1. Generate a key with ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
2. Choose where to save the key and give it a name (or just press enter to accept the defualt)
3. (Optional, not recommended) set a password when prompted
4. Start the ssh agent (the agent handles the process) eval "$(ssh-agent -s)"
5. Add the key to your computer's ssh agent ssh-add -K ~/.ssh/id_rsa
6. Copy the key to the clipboard pbcopy < ~/.ssh/id_rsa
- This is a great resource if you get stuck

Gitlab#

Accept the Fabcloud email invite from FabAcademy and create an account on the GitLab FabCloud Instance and complete the steps to create an account on the gitlab FabCloud instance.
Using the key that you have copied to your clipboard from the previous step, do the following:
- Go to your GitLab account settings
- Click ssh keys
- Click add key
- Paste the key you copied from the clipboard
- Click save.

Cloning the repository#

  1. Go to your student repository located at https://gitlab.fabcloud.org/academany/fabacademy/YEAR/labs/LABNAME/students/FIRSTNAME-LASTNAME.
  2. Below your name, there is a dropdown menu that shows SSH or HTTPS. Select SSH, then copy the path in the textfield. In my case, it is git@gitlab.fabcloud.org:academany/fabacademy/2019/labs/waag/students/heidi-hansen.git
  3. In terminal, navigate to the directory you want to keep your website directory in, and enter:git clone COPIEDTEXT

Learn Markdown Syntax#

Study this markdown syntax cheatsheet, this one or this one.
These are the markdown syntax commands I use:
# for a large header title
## for an h2 header
[description](url-path) for links
![](file-path) for images and files
` ` (backticks) for code highlighting
- for bullet points

Install MKDocs#

  1. Install Homebrew by entering this into the terminal:
    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  2. Install MkDocs with homebrew: brew install mkdocs.

Edit the posts with a text editor#

  1. Familiarize yourself with the project structure. In the docs directory, all of the weekly assingment posts are there and ready to be customized.
  2. Select a text editor. I use Xcode. Unless you're familiar with Xcode, I do not recommend using it for this project. I use Xcode because I develop apps with it and I know all of the keybindings for editing and navigation. I also use Sublime Text 3.
  3. Edit the following pages: About, Initial Project Idea, Contact Info, Student Agreement, and Welcome landing page.

Compress images#

  1. Install ImageMagick to compress images by using brew install imagemagick.
  2. To compress images, I referred to the FabAcademy ImageMagick encoding cheatsheet.
  3. I needed to convert an image from a svg to a png with convert -density 1000 -units PixelsPerInch input.svg output.png
  4. Then I resized it with convert input.jpg -quality 50% -resize 1000 output.jpg.
  5. Eventually, I realized it took too much time to convert and compress images one-by-one, so I experimented with and came up with a script to convert all images of one type in one directory. I needed to keep track of which images were and were not compressed, so my script includes moving the compressed images to a new folder. I wanted to resize all images to be no more than 400 wide and no larger than 80kb. All of the screenshots I took were PNG format, so I first needed to convert them into JPG format, then resize and compress them, then move them into a new folder called compressed/.
  6. mkdir compressed/ && convert -format jpg *.png -define jpeg:extent=60kb -resize 400 compressed/screenshot.JPG
    The -format flag does the conversion from png to jpg.
    Adding the *. before the png tells the terminal to apply this command to all files of this type in this directory.
    The -define jpeg:extent=60kb sets the maximum file size.
    resize 400 sets the maximum width.
    compressed/screenshot is the prefix for each new file where a - and number will be appended.
    Finally, .JPG is the file type suffix.

Test the website locally#

  1. After saving all edited files, return to terminal, navigate to the root directory of the project and enter mkdocs serve
  2. Open http://127.0.0.1:8000 in a browser to see if it builds!

Add a theme#

After customizing the site and saving my work, I ran mkdocs build to generate the static site pages. Then I added them to the project and pushed them to fabcloud with git add . && git commit -m 'commit message' && git push.

Customizing the theme and Configuring the site to work with GitLab#

  1. In the project root directory, create a file with touch requirements.txt
  2. Paste the following text into requirements.txt and save
mkdocs
mkdocs-material
  1. Create another file with touch .gitlab-ci.yml, paste the following text into it, and save. 
image: python:alpine

before_script:
- pip install -r requirements.txt

pages:
script:
- mkdocs build
- mv _site public
artifacts:
paths:
- public
only:
- master

Generating the Static Site#

Once the project files have been saved, use mkdocs build. This will generate a new directory in the root folder called _site where all of the compiled html files are stored.

Pushing the site to the cloud#

  1. Review the changes with git status
  2. To add all the changes to prepare to commit them, use git add .
  3. To commit the changes, use git commit -m "Setup static website using MkDocs"
  4. To push the changes to the cloud, use git push

Challenges#

Initially, I tried to install and set up a static site using Jekyll. I made many mistakes. Jekyll is a static site builder that relies on specific versions of Ruby and many dependencies. I have struggled with Ruby for years because there is a lot of "automagic" that happens in Ruby that is not visible unlike other software development tools. I attempted to install many different Jekyll Themes, but I failed in the end for the following reasons:

  • The themes were outdated and only worked on previous versions of Jekyll
  • The themes were complex, needed a high degree of customization, and I could not figure out how to customize them
  • I could not get the themes to build
  • All the links were broken
  • The themes required additional dependencies to be installed. I tried installing them but there were installation errors and version conflicts that I was not able to successuflly debug
  • They took too long to set up

Then, I tried to setup a static webpage with Gatsby. My motivation to do this is because I wanted to learn how to use React.js and get better at writing Javascript. This was a mistake. Javascript is the widely used programming language in the world today, but it is complicated and takes time to learn how to work with the modern javascript paradigms today.
It was nearly impossible for me to discern how complex a theme was going to be upon first glance. I strongly suggest using themes that other people have recommended and had success with. It can also be useful to look at the repository for the theme to see how many issues are filed for it and how recently it has been updated.

Videos#

Project Management(1:20:37) January 23rd, 2019 from Academany on Vimeo.

Recitation on version control(1:12:42) January 28th, 2019 from Academany on Vimeo.

Global review of this week's work(1:31:55) January 30th, 2019 from Academany on Vimeo.