01A. Documentation¶

This week was about setting up my website on GitLab. The main things in the following blog are: - the reason we use a version control platform like gitlab; - what are static website generators like Mkdocs; - how to create a use a package installer for Python such as anaconda to make all software version compatible - how to tweak already existing templates using CSS & JS ; - how to push using new templates

Why GitLab?¶

“As Gitlab is an open-source platform that facilitates version control of projects, it is the platform that will use to manage our documentation and projects.

Each student has their own repository. A repository is what is used to store your codebase in GitLab and change it with version control. Each one of us has to generate their SSH key as our personal login key for safe login.

git config -–global user.email “jSmith@mail.com”git config –-global user.name “lynn.dika"
git config -–global user.email “jSmith@mail.com"
git config -–global user.email "jSmith@mail.com"
git config --global user.name "lynn.dika"
git config --global user.email "lynn.dika@gmail.com"
cat ~/.ssh/id_rsa.pub
ssh-keygen -t rsa -C "$your_email"
ssh-keygen -t rsa -C "lynn.dika@gmail.com"

Let’s talk SHELL/BASH¶

” SHELL and/or BASH are the languages used to talk to the computer. They are used on the terminal.

I needed to think about the different commands for different softwares as speaking to individuals who speak different languages. That meant understanding that commands for MKDocs, Python, Pip & simply accessing different departments of my computer were different. “

Wait, what is MKDocs & how does it work?¶

” MKDocs is a static website generator. It needs Python for it to function. By writing markdown language, it translates it into html/css, which can be deployed into a static website through gitlab.

In order to use the MKDocs template provided by FabLab, I had two requirements, downloading mkdocs and mkdocs template mkdocs-material. “

Okey, so what is Python?¶

” Python is a coding language that is used by different packages to function. Those packages can be downloaded by pip, a package manager of Python”

And why did I make all of this clear?¶

” The first trouble I had was with Python compatibility. As my mac has already installed version 2.7 of Python, it was entering in conflict with the pip version and mkdocs version that I was downloading.

For that, I had to use Anaconda, to simplify the package employment in terms of versions. In that sense, I had Python language updated to 3.7. That was supposed to solve my problems.”

conda create --name myenv
conda
conda create --name myenv
conda activate myenv
which pip
pip install mkdocs
conda install mkdocs
conda list
conda install pip
which pip
pip install mkdocs
pip install mkdocs-material
mkdocs serve

Environment problem¶

” As an apple user, as I discovered, I am never really the full owner of my computer. I wasn’t being able to use Python 3.7 within the usual environment of my computer.

For that reason, I had to create a new environment in which I had more control of the authorisation of such installations.

sudo chown -R $USERNAME /Users/LynnDika/Library/Caches/pip
sudo chown -R LynnDika /Users/LynnDika/Library/Caches/pip
pip install mkdocs-material
reset
history
sudo -H pip install mkdocs-material

Once that was done, and in order to make things easier, I made my terminal automatically open my new environment .myenv so I do not have to do it everytime manually.”

create --name myenv

Environment problem: solved¶

Now that I have solved my authorisation issue, I was able to install using pip both mkdocs and mkdocs-material within my new environment ‘myenv’

pip install mkdocs
pip install mkdocs-material
mkdocs serve

The template was successfully installed. I was able to edit the files using atom. By using the mkdocs serve command, I was able to see the changes through a local host link generated.

git add .
git commit -m "<commit message>"
git push

In case only one page needs to be added, then we would use the command:

git add {filesource}
git commit -m "<commit message>"
git push

Using a third-party theme¶

After knowing the basics of how to handle Git & MkDocs; I decided to experiment with a more fun template. I chose Bootstrap386, a third-party template from the wiki of MKDocs. I downloaded through pip.

pip install bootstrap386

To do so, I had to modify some code within the mkdocs.yml by changing the theme name, adding a custom directory custom_dir which corresponds to the file in which all the html, css, js files of the theme are.

theme:
  name: bootstrap386
  custom_dir: "mkdocs_bootstrap386/"

HTML & CSS¶

As the code has already been written for the theme, I used the inspect option of google chrome to find the elements I neeeded to change. Some of my learnings in CSS were:

how to write different states for the same element
the difference between margin, padding & borders
different commands related to colours, shapes, fonts
the possibility of using percentages instead of measurements
how to make a footer fixed to a bottom of a scroll & not over-write on top of the body

Pushing this to Git caused me a couple of errors

ERROR - Config value: 'theme'. Error: Unrecognised theme name: 'mkdocs_bootstrap386'. The available installed themes are: mkdocs, readthedocs, material "

Learning: The requirements.txt was still containing the material theme provided by fablab rather than the boostrap386 one. Changing the requirements.txt solved the push problem.

Main plan¶

I will dedicate 30 mins weekly to tweak a detail that I would like to improve in the website. This way, I ensure getting to understand better