2. Project management¶

Tasks¶

This week I worked on the following tasks:

Making the website using mkdocs
Version control via git

mkdocs¶

MkDocs is a static website generator. By static it means that all the web pages are pre generated and served to the users as it is [wiki]. Back in the day when I was young, I had seen people developing websites using databases and talking in tongues. That experience made me realize that website development is one drug from which I am going to stay away for ever. Now, as I am old and questionably a bit more wiser and static websites are in vogue again, I have decided that this is one trend I can get behind on. Also, as I am required to make a website, so here I am writing Markdown. Basic syntax of markdown can be found here.

A template for the website was already available in the GitLab project, so I have started with that only. To make testing easier, I installed MkDocs on my local computer. I cloned my fabacademy project from the Gitlab and ran

mkdocs serve

in the directory where the mkdocs.yml file was present. This command builds the website and hosts it on the local machine. You can look at the website by pointing your web browser to 127.0.0.1:8000. The beauty of mkdocs serve is that it automatically builds and reloads the web browser whenever any changes are done in the source files.

I am using the default theme mkdocs-material. Below are the changes I did in the mkdocs.yml file

site_name: Fabacademy 2019
site_description: My Fabacademy site

site_author: Alok Sethi

Below is the directory structure of the website

alok-sethi/
├── .gitlab-ci.yml      –>sort of a makefile for the gitlab, tells it how to build the site
├── mkdocs.yml          –>mkdocs configuration file
├── requirements.txt    –>requirements to be fulfilled to compile the website
└── docs/
    ├── index.md        –>landing page
    ├── about
    │   ├── agreement.md
    │   └── index.md    –>about me
    ├── assignments     –>all the assignments are saved here
    │   ├── week01.md   –>week01 assignments are listed here and so on.
    │   └── week02.md
    ├── images          –>images are store here, week by week basis. just to keep files organized
    │   ├── week01
    │   │   └── final_prj.png
    │   └── week02
    └── projects        –>final project is documented here.
        └── final_project.md

git¶

In the past, I have used svn, clearcase and cvs, so the version control terminology is not alien to me. However, I have never used git thoroughly. I didn’t follow any tutorial except what was shown during the local lecture. Documented below are the various commands I used.

Below is shown how to generate the public-private key pair in order to access the gitlab via command line. This is mandatory if you want to access the git repository from gitlab via command line. Similar procedure is used to access an ssh server without a password. The only thing different is the copying of the public key.
Access the profile at gitlab.fabcloud.org, open the SSH keys tab and copy the contents of the previously generated public key there (the direct url is this).
clone the repository. This will bring a local copy of the repository from the server.
status. It tells you if there is any change in the local copy.
add files. This adds files in the staging area. Basically prepares the content for the next commit.
pull the repository. It updates the current HEAD branch with the latest changes from the remote server.
commit the changes. It stores the current contents of the index (things that were added via git add) in a new commit along with a log message from the user describing the changes.
git is a distributed version control system, which means there is a central repository and a local repository and you work on the local repository. in order to sync with the central repository, you need to pull the changes from the central repository and push your local changes to the central repository.
git rm file.txt –> this is used to delete a file. You still need to commit and push. Keep in mind that file still stays in the history so anyone with correct permissions can go and check it from the older versions.
git checkout file.txt –> this is to revert the local uncommitted changes.

The normal workflow with git includes cloning the repository (git clone), making local changes, staging them using add command (git add), doing a local commit (git commit) and when ready, do a pull (git pull) and push (git push) to the central repository.

Problems¶

Markdown cannot specify the dimensions of an image. So, either size the image before hand or use <img> tag. Use only one attribute say height or width to preserve the aspect ratio of the image.

<img src="/images/week02/add_key.png" alt="Add public key in GitLab" height="400"  width="400">

Keep in mind that the server is case sensitive i.e., all the file names are case sensitive so .PNG is not same as .png
Haven’t figured out how the lists and code block work together in the markdown. Putting the code block above messes up the numbering of the lists.
an empty line is required before starting a list. this seems to be the case with mkdocs and not markdown.