2. Project management

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

Process

Just to clarify, these were the steps of making my website.

1 First I took the mkdocs and try to set up my local repo and sync with gitlab. 2 After that I tried locally a couple of frameworks without much success 3 Then I set the default framework (MKDocs with material theme) that it was given to us. 4 Lastly I started edditing and adding content

Setting the webpage

First I wanted to try Markdown and MKdocs so I knew how much I could do with it even with the basics of the web already provided. That could train me with the git and see how was it.

Sweat with git

Even if I used git in the past, it was in a very specific and restrictive way (and preset by the sysadmins) so this was the first time using and setting git for myself.

The problem I had was with getting the ssh code and paste it properly in the fabcloud. Here you can see the tutorial

Git commands

I’ve used git in the past (in other computers). And even if when using it’s bread and butter, for me the setup it’s always tricky.

I installed gitbash (for windows). I like the context menu that they add with “git bash here”, pretty useful.

Then I follow step-by-step the tutorial with the bash opened in the folder that I want to have the repository (repo).

I set up my email and my username. Exactly the same that I have in gitlab so there is no trouble.

git config –-global user.name “USERNAME”

And

git config -–global user.email “jSmith@mail.com”

then I get my ssh key that.. it seems already done. (maybe because I already had an account or I made directly the last time)

cat ~/.ssh/id_rsa.pub

Then I go to the gitlab page and paste it. Important so I say to gitlab that I’m allowed to upload content!

After that I tried at home doing some commits and pushes at home

If you want to start from the template you're given you should open your *.gitlab-ci.yml* and add this code below "pages":

  stage: deploy

It should be something like this:

image: python:alpine

before_script:
  - pip install -r requirements.txt

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

the yml are picky in how much spaces put in the places so keep an eye on it.

Regular use of the git using atom

I use the text editor atom. In this case has an integrated git interface so I have in the bar a section where I can see what’s unstaged, staged, make the commits an pushes. (in this image you’ll see that my comments in the commits are usually which week i’m on)

pretty neat!

Easy explanation of basic commands.

Ok, in git you have timelines (well, they are called branches, but timelines are FUN). When you have a folder inspected by git, it takes notice of what do you change on it. Once you have enough changes (saved changes, that is), you may want to set a milestone in your timeline. That’s a commit. When it happens, you have to set what do you want to set as a point in that timeline (maybe you want 2 milestones because you’re doing somethg else). So you “add” or “stage” (in atom ui terms) those items.

Then you have a timeline in your computer. Now to send that timeline into the mainframe timeline you have to push it. If you want to take the content from the mainframe you have to pull them.

this is how it feels like to switch between timelines

Deciding the design

For this week (that we have to adapt ourselves to the fabacademy and sketch the final project and make the website) I decided to stick to something that I could update quickly and even if I know HTML and some frameworks (like Angular) they were not static or they would need some time to set up. So the Markdown idea was best for me.

I tried to install the local MKDocs to check everything before push to the web but I had the same problem of others that when I try to deploy the local server it gives me a Python unknown error. / later there is an issue in the fabacademy to solve it but I didn’t find it when I was setting up the web /

Finally I decided to stick to Material theme of MKdocs and later on I could tweak it when I have more documentation to work with.

Updating the avatar and images

I updated the avatar-photo.jpg and it was correct on my repo and in the fabcloud repo but it took a day to refresh in the public web. So just be patient with image replacing. To be sure of the image being properly updated you should only check the fabcloud repo.

The avatar was a recent image of the challenge “toonme”.

Problems faced

I have problems with Mkdocs when installed and server locally. Just a python not implementent error. = (

I couldn't install jekyll. I found this web with my same error but I couldn't make it work. [https://github.com/jekyll/jekyll/issues/7000](https://github.com/jekyll/jekyll/issues/7000) After some desperation, I uninstalled ruby 2.6.5, installed full 2.5.7 and rebooted the system. The powershell asked for some credentials it hadn't asked before and it worked! Now I can try to make a Jekyll site if I want. But, as I said, I prefer to keep going with MKdocs that's easier to produce.

The problem with div share

Using the div share given by the school there is a bug where if you put the div tag and there is anything else, such as header or an image it will break the mkdocs and the header or the image won't be parsed properly

Useful links found/used:

• My own repo on fabcloud

• Material theme for MKdocs

• 3dviewer