1. State of the art, project management and documentation¶
This week I started wayyyy too late, but couldn't stop once I started. And managed to put together a start page for quick refernce to future module documentaion pages, and an About me page,as is customary.
Research¶
Like all good needs analysis, we start by defining our problem space and our intentions. First the "requirements" set out in the assignment description, and a good look at what others have done for inspiration. Then a self-evaluation : what do I want to acheive here? * Get comfortable with the environment * Push a few personal boundaries (so much for getting comfortable) * Communicate something of use to others * Structure my workspace enough that the disorder does not get in the way of the work, or diminish its value.
Law of misplaced expectations: Everything takes longer than foreseen.
Patty Jansen's documentation (especially the terminal screen capture) and Fiore Basile's Gitlab presentation were extremely helpful, yet I ran into multiple problems.
Using Gitlab itself was not that much of a problem once I found a good list of markdown syntax and figured out that I could include HTML tags and even add footnotes[1]. The biggest stumbling block was that, like Patty, the changes took way too long to refresh. So I installed mkdocs and all went smoothly until I tried to clone my project. Things quickly got messy.
My SSH key was not recognized.¶
git@gitlab.fabcloud.org: Permission denied (publickey)<br>
fatal: Could not read from remote repository.
Getting my SSH key recognized was not that straightforward. These two resources helped figure out the problem and solution. Seems it was a Mac thing.
Finally I could clone my project
$ git clone git@gitlab.fabcloud.org:academany/fabricademy/2021/students/kalli.benetos.git
mkdocs wouldn't serve¶
(base) cassandra:kalli kalli$ mkdocs serve
INFO - Building documentation...
ERROR - Config value: 'theme'. Error: Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs
ERROR - Config value: 'plugins'. Error: The "git-revision-date-localized" plugin is not installed
A theme and a plugin referenced in the cloned project were not installed on my local version of mkdocs and gave errors. There, all hell broke loose. I have several virtual machines on my MacBook (work machine) and 5 versions of Python installed. I didn't think to change the default version when I initially installed mkdocs, so it was installed under Python 2.7 (used for an older app clone). The plugins wouldn't install with that version, so I added the latest Python (3.8.5), as suggested by mkdocs.org only to find that there were other incompatiblilities (things like regex and nltk that are integrated in Python 3.8 and not recognized by mkdocs in this case). Ahhhhh!
Then I came home and tried again on my iMac machine that is still relatively unpoluted. First I made sure I was running Python 3.7 (the version the mkdocs documentation refers to) by default and was prepared to change the default python version if need be before doing anything else.
(base) talos:~ hivequeen$ python --version
Python 3.7.4
yes!
I installed mkdocs again
(base) talos:~ hivequeen$ pip install mkdocs
I then added a new SSH key and added it to my mac ssh config file (see above link for details).
Installed the material theme (with pip3 or it would install)
$ pip3 install mkdocs-material
and the missing plugin
$ pip install mkdocs-git-revision-date-localized-plugin
and... SUCCESS! At least locally.
update¶
Since updating to Catalina, it was impossible to get mkdocs up and running again. I had to reinstall the mkdocs-material and mkdocs-git-revision-date-localized-plugin, but pip would keep pointing to old python versions and pip3 is now part of pip under Python3.8 on mac. To get around this, all pip and pip3 commands are to be prefaced by python3.8 -m pip.
Current start up¶
Go to workspace directory > ~/fabac/studentsite
python3.8 -m mkdocs serveand leave terminal window active for the session
Seeing the changes online still takes a very long time, so I'll have to plan to get everything done well in advance of any group sessions on zoom.
side note¶
- locally, I use Visual Studio Code instead of Gitlab. I use it for other projects and can push to github or other servers all from the same environment.
- Seems I have to make my mac use Python3.7 and install mkdocs-material each time I start up mkdocs.
- Sorted out my python and pip version problems on my macbook too and got mkdocs up and running locally... yeah!
Building the "About me" page¶
I extracted the gallery portion of w3schools pepole portfolio template.
Building the homepage¶
Borrowed much from Patty Jansen's page again again. Still trying to adapt it to my needs, but much and many thanks Patty. The markdown syntax guide over at markdownguide.org [2] is a constant help.