2. Project management

Goal

• Build a personal site describing you and your final project.

• Upload it to the class archive.

• Work through a git tutorial.

I found this week to be a bit intimidating as software / web design in general and writing in particular is not my strong suit. Nothing to gain by waiting so I dove right in.

Accomplishments

1. Got MKDocs set up and put up basic website

2. Set up git, learned basic operations via git tutorial

3. Set up my documentation website

4. Posted the student agreement

5. Documented Pre fab work and week 1

6. Put up basic sketch / overview of final project idea (in principle and practices page)

Installing MKDocs

Started off trying to install MKDocs. I linked off the mkdocs website into the " getting started " page

https://www.mkdocs.org/getting-started/

And from there moved to the installation guide at:

https://www.mkdocs.org/user-guide/installation/

Problem #1 - no pip or python on my PC…..

Installing Python

Tried installing Python from the website www.python.org but once I got back into the CMD that did not seem to work

After trying different commands in the CMD terminal the windows app store python came up!!! and after installing the app from there things seems to get back on track

After what I thought was success I seem to hit a wall to get more progress....

Visual Studio

Next we needed to get IDE in place.

This was very straight forward off the Visual Studio website

https://visualstudio.microsoft.com/vs/

Mattermost

Got the link to set up Matter most. Followed direction for Windows install

Added the channel from the fab admin email and logged in using the Gitlab button

And we are good to go

GitLab

This is a litte confusion but I fould a guide on https://docs.gitlab.com/ee/topics/git/how_to_install_git/

and decided to follow it. Step 1: Install GIT from https://git-scm.com/

Thanks I went ahead with the commands to install and create a key

Now I went ahead from Git Bash using the following command:

cat ~/.ssh/id_ed25519.pub | clip

Now the SSH was copied into my clipboard and the next step is to add that to GitLab

Under profile--> preferences there is an SSH Key option

and we are now goot to do...I think

So I decided to check but running the following command

ssh -T git@gitlab.fabcloud.org

Success!!!!

Learning basic git

Here I used the following tutorial

https://github.com/skills/introduction-to-github

I ran through the 4 steps:

Step 1: Create a branch Step 2: Commit a file Step 3: Open a pull request Step 4: Merge your pull request

This was pretty straight but the real test will be digging into Gitlab and my site

GitLab first steps

So now it is time to clone the repository. The command itself seemed easy enough but I did have to try a number of times until I got the address correct.

So now it is time to access the local repo and see if I can update something

I load Git Gui

It took my a bit of time to figure out were the repo cloned but I noticed it said "dan-stone" in the clone

A quick search located that folder in the top of the C: drive and so pointing the GitGui "open repo" got us rocking and rolling

Uploading my first website

So I have been diligently in MKDocs and ignoring the parts of the documentation that talk about "build" command....i have been using mkdocs serve to start a local site that I can view and it all seems great.

Well I decided to upload my website to git and it all seems simple enough....

I copy the MKDocs folder contents to the "Public Folder" in the repository and hit push

GitGui give me back a "Success" green light and I hit the public website address to find

It seems that other folks in my class had a similar issue at the same time and a discussion on mkdocs vs. html made me realize that I should probably go back and revisit the mkdocs build command.

I get a folder named "site" filled with html files of my website.

I quickly drop these files into my "Public folder" of the repository and commit a push....

Success....kinda of....web site is up but no picture are showing .....

I do some more research and looks like what I thought was the syntax for a relative pic link was not right.

I kept using ![title](/folder name/name of image.jpg)

but is should be ![title](../folder name/name of image.jpg)

Quick correct, new build and upload and we are good to go!!

Finally used Adam Stone's documentation to learn how to ensure all my pics are the same/good size on the page https://fabacademy.org/2023/labs/charlotte/students/adam-stone/lessons/prefab/image-resizer/

Publishing website + learning how to hard reset git

So just as I thought everything was going well...it did not!

Problem #1 - I started off by uploading my MKDocs doc folder and 404....

So when I got the 404 error I looked at the existing files in the pre populated Public folder and they were all HTML. I said to my self - I can do that.

Quick visit to the CMD `` MKDocs build ``` and we had a new folder full of my site in html.

I uploaded that and we went live.

Success and problem #2 - So that was successful but not very elegant because every time I change something I need to go back to the CMD, do another build, and replace files in repo / push.

I discuss with my instructor and it seemed like MKDocs should work on git if I use the right template.

I cloned the fab student MKDcos template

https://gitlab.fabcloud.org/fibasile/fabacademy-student-template

How it should work

Step 1: clone the fab student MKDocs template repo

Step 2: This Template runs a MKDocs theme calls materials and has a revision date tracking in it. These two things need to be installed in your repo.

CMD into the your repository and run the following two commands

pip3 install mkdocs-git-revision-date-localized-plugin

pip install mkdocs-material

These files should be in the main folder (no the public folder)

Step 3: Edit your MKDocs files and push them to your git repo.

The website should be up and running now.

These files need to be uploaded to your general folder, not the public folder

Jammed up in the pipe and learning about a hard reset

When I attempted to follow the 4 steps above I ended up moving all my files into the public folder. My commit got stuck, did not fail, just did not get a status. Tried this a few more time and none of them got a status.

After a few more attempt, an instructor in our lab, Dr. Taylor tried some and still nothing moving

I gave it some time but no joy.

I have everything backed up so I decided to revert previous commit but got this message

So after a few hours of google searching, consulting other folks in the lab I decided to reach out and ask to have my account reset.

Julian Gallimore was very helpful in reverting and setting up the MKDocs template in the right place.

He explained that the resolution was running a hard reset

git reset --hard b5110504fed4253ca5f5c82a394fb3c591372818

This command will move the HEAD (pointer in your branch) to the commit for which you want to revert. He also added that the tricky part is one needs to "force" push, which requires a setting change to allow it.

THANK YOU Julian!

Once that got all cleared, I just cut and pasted my content into the new template, pushed it to git and the lovely green check mark showed up!

Using Visual Studio git capability

Finally, MKDoc was working on my site and I learned from Adam Stone that VS has a built right into Git this streams lines the update so much.

open my local repo and we are good to go

---

Last update: March 26, 2023