1. Project management¶
This week, I began and finished the steps for setting up my website. This consisted of installing git, python, mkdocs, vs code, setting up my ssh key, and cloning my repository on gitlab.
Generating my SSH key¶
The first thing I did was install and setup git. This was pretty easy as all I had to after installing it was enter my username and email address. After setting this up, I generated my ssh key and pasted it into gitlab. The command I used to do this is shown below:
ssh-keygen -t rsa -C “your_email”
After this, I used the following command to see and copy my ssh key:
cat ~/.ssh/id_rsa.pub
Now that I had copied my public key, I went to my account in gitlab, clicked on the tab named ‘SSH keys’, and pasted it in. This made sure that the information on my local computer could be linked to the online server for any future changes I needed to push.
Cloning the Repository¶
Now that I was done setting up my ssh key, I had to clone my repository, and this is where I encountered my first issue. At this time, I was following Adrian Torres’ Documentation, where I saw this line of code:
git clone git@gitlab.fabcloud.org:academany/fabacademy/2020/labs/leon/students/'file name'.git
Initially, I tried to paste this in my computer’s terminal and immediately run the code after replacing ‘file name’ with ‘ryan-zhou’, but this resulted in an error, with the terminal displaying that the file ‘ryan-zhou’ did not exist even though I had already created a folder under that name. After struggling with this for about half an hour, I realized that I had to first navigate to the specific directory my folder was contained in using the ‘cd’ command before running the code. After doing this, I successfully cloned the repository.
The image above shows the final step of cloning in my computer’s terminal.
Setting up mkdocs and Python¶
Now that my repository had been successfully cloned, I could setup python and mkdocs to actually begin editing my website. After first installing python, I ran the following command into my terminal to install mkdocs:
pip install mkdocs
Following this, I also installed Visual Studio Code (vs code) in order to open my yaml files. Now that I had mkdocs installed, I ran the following (very useful) lines of code which I found by following Griffin Orsinger’s documentation:
mkdocs new <Project-Name>
cd <Project-Name>
mkdocs serve
These 3 lines of code allowed me to create a new project in mkdocs. I then opened my file in vs code, which contained a very basic template for my website I also downloaded a file called ‘requirements.txt’ and created my first commit, which worked successfully with no issues.
Creating the website¶
Following this, I wanted to change the basic template I was provided with, so I downloaded a template which I got from Angelina Yang’s documentation and saved it as a zip file onto my computer. After unzipping it, I copied all of its contents into my file named ‘ryan-zhou’ (the same one I had in vs code) and expected to see its contents successfully integrated. Unfortunately, after this didn’t work, I realized I had made a mistake. After searching for a while, I finally realized that I had skipped the following line of code when installing mkdocs:
pip install mkdocs-material
Because of this, I was unable to use the template I had downloaded. After fixing this by running the code in my computer’s terminal, I successfully opened the template and its contents in vs code.
With my newly downloaded template, I now wanted to create my second commit and push the changes to my website. In order to do this, I used the following code:
git add .
git commit -m "<custom message for commit>"
git push
However, after entering these commands, I received an error message stating that the file ‘docs’ was not found and that the commit could not go through. Luckily, fixing this error wasn’t too difficult as it was fixed by simply renaming the ‘public’ file from my downloaded template to ‘docs’.
Now that this issue was fixed, I tried to make another commit. This time, however, I encountered another error:
ssh: Could not resolve hostname gitlab.fabcloud.org: Name or service not known
fatal: Could not read from remote repository.
Please make sure you have the correct access rights and the repository exists.
At first, I was very confused by this message because I had already cloned my repository using my ssh key. However, after asking one of my classmates, Angelina Yang, I decided to just make another ssh key and replace the old one. This wasn’t too difficult, and, after doing this and adding the new ssh key onto my account in gitlab, I was finally able to use the ‘git commit’ and ‘git push’ commands to add my new changes onto my website.
Reflection¶
Overall, I feel like this week went pretty smoothly. Other than a few minor errors along the way when trying to create my website, the setup went well. The only major problems I encountered were when I tried to import a theme folder into mkdocs and when I tried to push my vs code changes for the first time. I want to thank Adrian Torres, Griffin Orsinger, and Angelina Yang for their extremely helpful documentation, as I would not have been able to create my website without them.