1. Project management¶
Using GIT¶
Installing GIT tools¶
To start I went over to the git for windows website and downloaded their installer to install Git SCM. As an added bonus I also got a Bash emulator. Which I do like and is more powerful than the windows commandline.
I used to work on a linux machine and it is also nice to see some familiar tool available.
The Git system gives you version control over your files in a repository. For the fabacademy we have to keep a log or journal on a website. To maintain the website we use Git.
To get Git locally, It is useful to have an SSH Key to authenticate yourself. You can create an SSH key in Bash by using this line of code:
ssh-keygen -o -f ~/.ssh/id_rsa
To link your fabcloud git account to your local machine, you have to enter your ssh key into your profile on https://gitlab.fabcloud.org/profile/keys. This way your computer and your repository are linked and you will be able to work on Git from your computer. First we have to configure our Git by setting our name and email.
$ git config --global user.name "[name]"
$ git config --global user.email "[email address]"
Basic GIT usage¶
Info on the basic usage we found on https://git-scm.com/doc
Normally you can start a new repository by using this command
$ git init
But our website was already set up on our repo, so we had to clone it to use it locally
$ git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/barcelona/students/kurt-vanhoutte.git
Once working in your repository you have different commands to keep it up to date and synchronised.
It is always good to start with fetching and merging all remote files to your local branch. We use these commands to do that:
$ git fetch
$ git merge
Or you could used
$ git pull
which combines both above commands
After creating or editing some files you can update your repository by adding and commiting the files.
git add FILENAME
git commit -m "I did some editiing in this file"
Next you can use this command to upload the local branch to GitHub
git push --all
2 other useful commands that get used a lot are:
git status
Shows what is the status of your local/remote repository - if there are local or remote changes, or things to be pushed
And
git log
Shows the history of the local and remote repositories as a list of commits with more info:
using Atom and MkDocs¶
I never saw or used Atom and it looked nice to try. So I went to install it and directly added some packages to make it even more useful. The build in package manager makes it super easy to add functionality.
-
I added the gitlab package so i could pull and commit files to my repository from within the editor. That saves me from going back and forth to the git-bash commandline.
-
I also added a markdown preview extension, because i thought it would be nice to be able to preview changes inside the editor
That was nice. But I noticed that the preview did not show all of the theme styles, navigation did not work good, and so on.
To test the editing I did in Atom i tried installing MkDocs server locally.
Installing using
pip install mkdocs
that worked, but would not run because it was not in my windows PATH. so i had to put the scripts folder in the PATH environment variable.
$ PATH=$PATH:/C:\Users\Kurt\AppData\Roaming\Python\Python39\Scripts
This added to my PATH, but the mkdocs serv command still didn’t work.
When looking at my PATH variable i could see the path to my Python script folder was indeed added. But it still would execute I got
$ mkdocs serve
bash: mkdocs: command not found
So i went looking around the interwebs for tips. I found i could make a .bashscr with a reference to my PATH in it.
After that i got the mkdocs serve command working, but i encountered another error message. It seems i have to install the ‘material’ theme and some plugins first.
I went to https://squidfunk.github.io/mkdocs-material/getting-started/ to see what to do here to install the theme.
pip install mkdocs-material
did the trick After that i also had to install the git-revision-date-localized plugin. This was also done using pip
pip3 install mkdocs-git-revision-date-localized-plugin
SUCCES! I can now run the mkdocs serve command and look at my website local on my laptop.
Adjusting the website look and feel¶
I want to keep the site building clean and simple and reuse the demo site.
This site uses a theme called ‘material’(https://squidfunk.github.io/mkdocs-material/)
I am tweaking the theme settings a bit in the mkdocs.yml file. Mostly to change colors and icons.
I was able to use a new favicon I created and I also used that as a logo image on the top navbar.
I wanted to make a home page with a grid of squares that link to each week assignment. I tried adding HTML code to the page to use a <table>. that works, but it looked like using images inside the table is not supported.
I tried some other markup and didn’t want to do it.
And then it hit me.
YOU CAN’T USE MARKDOWN inside HTML tags!
Playing around¶
As an excercise in Git i did a couple of things. I used the git-bash terminal to try out the workflow of cloning and commiting files.
Since Isabel and me are doing a final project together it seems useful to be able to both use the same “final project page”.
To do that I tried to fetch a clone of her repository and try to adjust some files in it.
After getting access as a developer that worked fine. Now I can edit things on both websites.
To go further I also made a new project where I plan on keeping files for our final project.
But the next day I was thinking that cloning someone else’s repo can not be the best way to work together on some pages. So I did some more reading on http://git-scm.com/docs/gittutorial and https://gitlab.fabcloud.org/help/user/index.md
And now think it would be better to make a branch of the repo instead of cloning it.