2. Project management¶
Tools used¶
- mdocs
- vscode
- github
mkdocs¶
The website you are on is made using mkdocs. In the future this should serve as the hub for all my fab academy projects and their documentation.
The site can be pretty barebones IMO. But I have a feature wishlist I will attempt to implement. Also I want to change the theme to something snappy.
Rocket¶
Inspired by the Factorio devblog (scroll to the bottom!) I wanted to have a rocket on my site that takes the user back to the top.
I googled around for a bit and found a really neat script. All credit to the creator, “Prince”
Turns out that mkdocs and markup quite handily let me insert my own HTML/CSS/JS level code. It actually works!!! Scroll down and click the rocket for magic :). I still want to figure out how to auto-apply the rocket to all the pages. I imagine it’s a config option in the yml.
Of course, things aren’t always that simple. The rocket worked well on my local server, but broke when migrating to the fab academy one.
UPDATE Rocket needs JQuery to work. Somehow my local server pulled JQuery from another project, which the web version does not. I added JQUery and the rocket works now…ish. It now breaks when moving through the site links, and unbreaks when the page is reloaded. Will investigate further.
UPDATE 2: Rocket got fixed by disabling the instantaneous site reload feature. Now webpagesload a bit slower, but the rocket works!!
I might switch the rocket for my own design at some point. Could be fun with a cubesat for instance. Or maybe something historical. Or the Tintin moon rocket? Endless possibilities.
Github¶
For version control I already had github installed from a previous project, so it seemed natural to continue using that. For github to work, we need to get a few things rolling first:
SSH¶
SSH or secure shell, is an encrypted communications protocol. Useful for sending info to a server, and making sure nobody else can mess it up.
Fun fact: SSH, according to Wikipedia, was developed by a Finn!
Conveniently, Windows 10 has OpenSSH, an SSH implementation preinstalled!
To get a secure connection to a server, a key needs to be generated and shared with the server. The key is generated through command line with the ssh keygen command
There are a bunch of different kinds of keys. RSA is the oldest kind, and most insecure. ed25519 seems to be quite good so I went for that.
I followed this tutorial found on gitlab.
TL:DR
+ type “ssh-keygen -t ed25519 -C “
Through some Microsoft dark magic, github simply needs to check a box, and then plays nice with the system keys. I daren’t find out more how this works…
To get the repository cloned from gitlab, copy the HTTPS from gitlab and enter it into “clone a repository” in github. Now github will copy the files to a selected folde ron your computer
Finally, when changes are made to the files, github registers that and lists changes. They can then be staged to a commit, and pushed to the repository.
Easy as that.
VScode¶
I am currently writing text directly into VScode. It auto detected that i’m writing markdown, and adjusts all the pretty colors to match.
I really like VScode, and the more I use it, the more I appreciate it’s genius. For instance, did you know that you can use ctrl+D to get multiple cursors and edit multiple occurrences of a string at the same time! Amazing.
I installed some extensions, such as a spell checker, and an image paste tool. I can now directly paste images from the clipboard into markup with ctrl+alt+V!
The downside is that the images populate the default folder. I might want to restructure the .md files into the weekly folder. Will investigate.
Furthermore, the interoperability with github is nice (unsurprising seeing how Microsoft owns them both)
Image handling¶
Due to the image workflow described above: I decided to file the weeks in their own folders. How does one make a lot of numbered folders?
Python of course!
import os
path = "C:/Users/User/Documents/GitHub/arthur-tollet/docs/assignments"
for i in range(20):
if i < 10:
num = "0" + str(i)
else:
num = str(i)
try:
os.mkdir(os.path.join(path, "Week" + num))
except OSError as error:
print(error)