1. Principles and practices, and Project management¶
This week I worked on defining my final project idea and started to get used to the documentation process.
Setting Fab Lab GitLab Site (SSH KeyGen, Git)¶
Git is a distributed version control system that tracks changes in any set of computer files, usually used for coordinating work among programmers collaboratively developing source code during software development. To set up the GitLab site, I followed the instructions mentioned on the Fab Lab Oulu’s Gitlab site. Given that my background is Computer Science, I have used Git many times in the past. So, setting up Git was not a new lesson for me.
After generating SSH public and private keys, I uploaded my private key to my Git Repository.
Initially, I cloned Fab Lab Oulu’s GitLab site to my local computer by mistake. Afterwards, I followed the same step to clone my Git repository to the local computer. I first got the URL from the Git repository site which I used to clone the repository to my local computer.
I forgot to take a screenshot of configuring my git username and git email. These commands were used to set git username and git email:
git config --global user.name "my user name"
git config --global user.email "my-imaginatory-email@gmail.com"
“my user name” and “my-imaginatory-email@gmail.com” need to be replaced by the actual username and user email ID.
After configuring my username and email, I used these commands to upload changes in the local repository to my Git repository.
In summary, the following commands are important for setting up git on the local computer initially:
ssh-keygen -t rsa -C "userid" -b 4096 (generated ssh public key should be added to git web account)
It generates an SSH public key and an SSH private key. A public key should be added to the git web account. The private key is specific to the local workstation and should be always kept secret.
Why do we need to set SSH keys? Setting SSH keys ensures that changes in the git repository are always done from an authorized workstation. By setting up SSH keys, git repository can be connected without the need of entering username and password during evey single visit.
git clone git@........../site.git
It clones the git website and creates a local repository.
git pull
It corporates changes from a remote repository into the current branch.
git add --all
It updates the index using the current content found in the working tree, to prepare the content staged for the next commit.
The following commands are important for updating any future changes in the local git directory to the git website:
git status
It shows paths that have differences between the index file and the current HEAD commit, paths that have differences between the working tree and the index file, and paths in the working tree that are not tracked by Git
git pull
git add --all
git commit -m "mkdocs_version"
It records changes to the local repository which would be reflected in the git website.
git push origin main
It updates remote refs along with associated objects in the origin branch of the git website.
MKdocs¶
First unsuccessful attempt for using mkdocs¶
During week 1, I tried to use the mkdocs template but it was not successful. I uploaded the mkdocs template in the wrong directory. Week 1-8 assignments were done in HTML. Aarne helped me in setting up the mkdocs version.
Second successful attempt for using mkdocs¶
I downloaded the mkdocs template from Fab Lab Oulu’s Fab Academy site and put it in my git directory. It worked successfully this time. The followings are important files for mkdocs:
- .gitlab-ci.yml
- mkdocs.yml
- requirements.txt
- public/
- docs/index.md
- docs/assignments/week01.md
- docs/assignments/week01/
- docs/assignments/week02.md
- docs/assignments/week02/
- ...
- docs/about/
- docs/about/index.md
- docs/projects/
- docs/projects/final-project.md
As shown in the taxonomy above, the docs folder contains the files needed to build the site. Index.md is the landing markdown file of my Fab Academy page. The assignments folder contains the markdown files for weekly assignments: week01.md, week02.md… and the folders docs/assignments/week01/ contain the files for the weekly assignment files. The folder docs/about/ contains the file index.md, where I wrote information about myself and the folder docs/projects/ contains the file final-project.md, which is about the final project.
To work with mkdocs version on my local computer, I installed VS Code. It renders md file into html format which would appear on the website.
More on MkDocs¶
- Q1. What is a static site generator?
Static site generator (SSG) is an engine which uses user input text files to generate static web pages. Static web pages primarily use HTML language. Thus, SGG generates HTML code from user-input text files.
Once these static web pages have been generated, they do not need any backend engine, i.e. web pages generated by such site generator engines (such as Mkdocs) are persistent.
- Q2. What is Mkdocs?
Mkdocs is a static site generator which converts input text files written in markdown language into static web pages. It is widely used in the building project documentation.
- Q3. What is Markdown? Give an example.
Markdown is a lightweight markup language used to create formatted text. Essentially, Markdown describes how should the given input text look, and the Mkdocs engine renders the input text into the format described by Markdown.
For example, the following text is written in Markdown, which describes an image and the corresponding image caption.
*AR Thumb Controller Prototype - Copyright SoundxVision Oy.*
Mkdocs renders into the following HTML code:
<p><img alt="" src="../../images/final-project/thumb.jpg" /><em>AR Thumb Controller Prototype - Copyright SoundxVision Oy.</em></p>
A list of the basic syntax of markdown can be seen at MarkDown Guide’s website.
- Q4. What is the purpose of mkdocs.yml in Fab Academy’s Mkdcos template?
mkdocs.yml contains the settings for the server site.
Within mkdocs.yml file, I modified the default values of these paramaters: site_name, site_description, and site_author as follows:
site_name: Fab Academy Abhishek Kumar
site_description: My Fabacademy site
site_author: Abhishek Kumar
Changing these values allowed me to make website more personalized to me by setting title and my name. Properties (or paramaters) in this file seem to be acting as gloabl variable.
- Q5. What is the purpose of .gitlab-ci.yml?
The .gitlab-ci.yml builds the site on the server site and moves it to the public/ folder. It the necessary parameters and commands necessary for the CI/CD engine in gitlab buld the site and deploy it in a web server.