1. Principles and Practices, and Project Management

This week I worked on defining my final project idea and started to getting used to the documentation process. I also worked on setting up my webpage and learning about Git. In my eyes, this was a boss-battle- treading into uncharted waters- wrapping my head around the fabulously frustrating concept of Git/Gitlab and what not!

This week’s documentation is divided into TWO categories:
1. Setting up of Webpage
- Web IDE and P5.js integration
- Git
- Markdown
- Mkdocs
2. Website is up!
- Themes in Mkdocs
- Serve Error
- Uploading Videos
- P5.js code in Mkdocs

1. Setting up of the Webpage (the Boss-Battle)

Initial stages..

I have moderate proficiency with HTML but have never used Gitlab. I was confused as to what gitlab even was. So, like any newbie, I asked chatGPT to explain gitlab to a beginner (ME).

My Understandings from this:
Each project has a repo.
Commit = saving a repo edit.
Push = reflect on your webpage.
Pipeline is the Git CI/CD thing.
CI/CD = Git’s method of web development

Playing around in HTML (On Web IDE)

I then began playing around in Gitlab and the Gitlab Web IDE. I changed some basic code to get a hang of it.

My first change:

Then I changed the font through style.css:

Finally, I added a p5.js sketch in the background (Had some background HTML knowledge; Created a sketch.js and ‘called’ it in the index.html using < script >):

I wanted the p5.js to be in my background. So I quickly googled how I could get that done. I used Coding Trains tutorial to finally achieve this:

Few mess-ups along the way:

Git the hell out of my mind!

(Git set-up and Repo Local Cloning:)

So, here I started by understanding Git. And VScode.
Creating and connecting the local repository was a task as I was getting config errors while running the git commands.

The first error was this config error:

Here, the system was creating a “.config LOCK file” and hence the config was not taking place. This error persisted till the very end. After trying to find out why it was occuring, I decided to move on. Even deleting the lock file was not helping- it just created the lock file again or gave a permission denied error.

Then, the next error was in the cloning of the Repo.

Then, I created the SSH key using the ssh-keygen -t rsa -C "-my-email-address-"

An SSH key is a set of characters that help identify you on the server, while the fingerprint helps identify the server to your machine. (This was clarified to me later on by Ivan, my global evaluator. So thank you!). This ensures security over the internet.

After that, I went to Gitlab > Account > Preferences > SSH KEY and Added a New SSH Key.
Here, I copy-pasted the SSH I had generated using the git commands (It was in the .ssh folder on my system) and clicked on Add Key. Now, the server knows who I am.

Special mention to Adrian’s and Ricardo’s Tutorial as that helped me a lot in figuring this out! I would definitely urge you to refer to them in case you are new to this!
Also, would like to mention our mentors Jesal sir and Pranav sir, who helped us not only UNDERSTAND version control but also how we can set it up and use it effectively!
Julian’s Recitation was also super helpful!

Mentoring in process

Finally, the cloning was successful!

The SSH ~T was to test the connection as mentioned in Ricardo’s wonderful tutorial!

Next, I downloaded VSCode and could open the local repo from there.
But the CONFIG ERROR PERSISTED.

I was able to edit the repo pages but was not able to commit or push the changes.
Finally, I resolved this by simply using: git config user.name or git config user.email
instead of using the word ‘global’.

And it worked! I was able to commit and push changes to the web.

Changes I made using VSCode being reflected on the web

And then…Enter Markdown!

At some point after this, my instructors advised me to use Markdown to make the webpage.
“This would greatly reduce the mental burden while typing the text”, they said.

Helpful note:
Make use of The default Markdown Preview to understand the markdown code basics. It’s fairly easy to grasp and simple! All the best!

Red is the text I edited on the left side being reflected on the right side.
Blue is the Reset button so that you can get the preview page with the basic markdown syntax.

The best part of Markdown is that you can use HTML code too! For example, see how I’ve done the strikethrough in the upcoming title:

And in the text color above:

Descend to Madness Markdown

I installed Python from their website (Keeping in mind to positively check the “link to PATH” while installing)
Then I ran the command pip install mkdocs on git bash to install mkdocs.

After this, I followed the mkDocs tutorial given here: Tutorial to create a new project.

Creating a new project in mkdocs:
mkdocs new my-project

mkdocs serve

Click on the underlined hyperlink to open the served site

What this does is essentially creates a live reloading site out of our local repo. This is helpful in making quick changes to your code and seeing the outcome instantly. Be sure to press Ctrl + S to save the change on your text editor for it to reflect on the Served website!

Finally, I downloaded the zip folder of the student template for mkdocs provided by Fab and replaced my HTML local repo with the unzipped folder.
Here is the link to the Template.
You can download the entire zip file, unzip it in your local repo and get started!

I did not make any changes to the gitlab-ci.yml. However, I did edit the mkdocs.yml file to incorporate my name and details instead of the dumym text.

A little about YML files:
I think CHATGPT sums up YML files pretty well:
- The .gitlab-ci.yml file is used to define the pipeline for GitLab CI/CD (Continuous Integration and Continuous Deployment). This file is stored in the root directory of your repository and contains the instructions and stages for how your project’s code should be built, tested, and deployed.
- In MkDocs, a yml (YAML) file is typically used for configuration purposes. The primary configuration file in MkDocs is named mkdocs.yml. This file contains settings and options that control various aspects of your MkDocs project, such as the site name, theme, and the structure of the documentation.
- YAML stands for Yet Another Markup Language which is a “human-readable data serialization format”.

2. And the Website is Up and running!

Using Git for Website Management

Via commandline:

There are four main git commands which you can be using via the command line.
These are:

git add: This “stages” changes. It’s like getting ready to send the changes off to the pipeline.

git commit: This records changes in the staging area into the repo history.

git push: sends the changes to the remote repo so that it can come on par with the local repo.

git pull pulls the website back to where your local repo is.

A general process of your documentation would look like this:
1. You make changes on the local repo.
2. You do git add > git commit > git push in that order.
3. If by accident or error, your local repo runs behind your remote repo, you do git pull.

Always remember that the website is a reflection of the remote repo. In mkdocs specifically, “Serve” is used to see the reflection of the local repo. I have spoken moreon this later.

via VScode:

In VScode, things are a little simpler. As soon as you make any changes, you can use CTRL+S to save them. Then they will show up on the side panel as a change that you have made. You can also turn on auto-save by going to File and Preferences.

Here, in order to add, commit, and push, you simply click on the drop down arrow and select “Commit and Sync”.

A dialogue box pops up. Select YES:

This is automatically add, commit, and push your changes.

Make sure you give a comment in every commit as it will show an error otherwise. Try to keep your comments relevant to the change you made as it will be easier for you to see what you changed when later one.

Themes in Mkdocs:

You can choose different themes for mkdocs. Each theme has it’s own unique layout and color scheme (though, colors you can modify by yourself)

Find a good theme from here: Mkdocs Theme

Install the theme by running the command pip install mkdocs-material to use the Materials theme. I did not initially install it, just changed the theme name on the yml file directly to Materials. It worked in the moment but gave me an error when I wanted to do an mkdocs serve. I have mentioned this in the section below this.

You can then go to the yml document and change things as per your need. For example, change color or font.

You can also add in your other details like Social Media links etx.

Mkdocs Serve Error:

Initially, when I ran mkdocs soon after setting up the page, it gave me 2 errors:

First, it could not identify materials in the theme section
And secondly, the git-revision-date-localized was not installed.

However, my YML file did contain both! And it was working because I had changed the color of my Materials theme to black, and the commit/push was working smoothly.

I realized that I had not installed the theme, just had changed the text on the mkdocs.yml to the desired theme.

So, I referred to this guide and I ran two commands:

pip install mkdocs-git-revision-date-localized-plugin
and
pip install mkdocs-material

Then doing a pip list showed me a list of plugins where both of the above were present. And the serve was successful. Problem solved!

Mkdocs Videos:

My instructor gave me advice that I will need to install a plugin on mkdocs in order to embed videos successfully. The installation goes as follows:

pip install mkdocs- video

And you enable it in the YML by adding the plugin name mkdocs-video under the plugins. However, that was resulting in an error.

Additionally, the mkdocs serve command won’t work, and an open served webpage with crash.

Update:
I finally tried again after a few days. This time, I followed this mkdocs tutorial and added the following code to my mkdocs.yml under plugins:

  - mkdocs-video:
      is_video: True
      video_muted: True
      video_controls: True
      css_style:
        width: "50%"

And the Mkdocs video worked without causing any error!

I’m still not sure why the HTML tags won’t work but for now, I will go ahead with this!

Trials:

![type:video](../images/week01/trialvid.mp4):

<video width="640" controls>
<source src="../images/week01/trialvid.mp4" type="video/mp4"></video>

<figure class="video_container">
<video controls="true" allowfullscreen="true" poster="../images/week01/serveerror.png">
<source src="../images/week01/trialvid.mp4" type="video/mp4">
</video> </figure>

Youtube embed of my previous project on dystopic VR worlds:

Vimeo embed of another LP song:

Linkin Park from Joshua Michnik on Vimeo.

Setting up a P5.js code as my landing page background:

I had done this on my initial HTML trials. Now, I had to figure out how this could be done on mkdocs.

I created a new folder in my repo and named it ‘javascripts’.
Under this folder, I create new text files and saved them with the .js extension. These text files were the javascript code of the P5 sketch.

Then I went over to my landing page’s MD file, which was named ‘index.md’ and added the lines:

<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.1/p5.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.4.1/addons/p5.sound.min.js"></script>

<meta charset="utf-8" />
<script src="./javascripts/circlepattern.js"></script>

The above lines are derived from the P5.js editor by going in the HTML code of the sketch:

Initially:

And then:

Same pattern as my T-shirt:

Note:
In order to get the P5 sketch to cover the entire width and height of the page, use the following code while creating the canvas in the sketch.js:

function setup() {
    mycanvas= createCanvas(document.documentElement.scrollWidth, document.documentElement.scrollHeight, WEBGL);
    mycanvas.position(0,0);
    mycanvas.style('z-index','-1');
}

The z-index is set as -1 so that it goes behind everything else on the page.

Also, try to make the sketch.js as light a file as possible, otherwise it will start hanging your webpage- which is currently happening to me. Hence I have removed the sketch for the time-being.

Class Summary and Lecture Notes:

Wednesday- Our very first class was really exciting. I was as nervous as I was excited to be there!

Running notes during week 1 class:

Class 1 Running Notes:
- Antikythera mechanism- google.
- Self assembling machines
- Evolution of computers into household devices
- Similarly, evolution of fablabs
- 22 types of Amino acids as lego..play..each combination helps move a muscle
- Apple cutting example
Examples:
Work green-red light Do not disturb
Cat with moving hand..Laser on hand to keep cats moving
Biteable- Short videos website, Kdenlive- video editing.
Plant moisture monitoring with light to tell you when to water it
Self watering plants
Barber chair, base has vacuum, hair goes into it
Solar tracking
Nyctophobia lamp
Mediation pebble. Color, duration, flower pattern etched. Breathing sessions. Touch sensor for starting- circular body. Good finish
Quantum sensor for magnetic waves
Remote car control

Advice:
Save videos ppt etc in lowercase
Rsync for synchronization
https://docusaurus.io for markdown web
A next step to play with Markdown, you can set up MkDocs (simple website using Markdown). https://squidfunk.github.io/mkdocs-material/getting-started/ ~Julian
I have a few samples: here is mkdocs example: https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-mkdocs
gitbook- guide
dangit git- problems

Common Mistakes-
Set location and permission
Commit only pictures you want to show in docum
Use relative links not absolute
avoid spaces and non ASCII
All work has to go to repo except v large files
Images in kb…mb/week/person
gitconfig- who u r
ssh- which server
Only 5 commands u need: ~Rico
Pull, Add, Status, Commit, Push
Stay away from the dot syntax as a beginner ~Kris

Time management:
Final 5% of a project takes as much as the initial 95% (80:20)
Supply side: Plan, Preplan
Demand side: Task> Task > Task
Another common mistake is using the wrong case for your filenames, especially for those on Windows OS. Gitlab is case sensitive. You need +- 10mb on a single commit, uploading this file would break my git. 10Mb per commit, not specifically per file. 3+4+4=commit failure.
All files on the commit = less than 10mb
Triage: Who’s gonna die, Who’s gonna survive, Who’s at the boundary. (Project prioritizing)
Serial: Task>Task>Task. Get stuck, halt
Parallel: Not at the same time so not stuck
Spiral: Sketch, Cardboard, Wood, Composite, Add motor.
Basically progressive iteration.
Mythical Man Month- Book on Project management by IBM dude
Mattermost = chat