Working, Finally

Project Management and Documentation, Part 4

Oh, what a roller coaster ride this has been.
I sit here writing this in Week 6, when I've eventually managed to get this working.

I finally sat down today for a several-hours-long session to get the documentation website going properly, instead of relying on my GitHub pages latch-on.

Documentation Site

I had earlier attempted to follow Jogin Francis' advice and had downloaded Adam Stone's (AS) repo. It hadn't worked at the time, but now I was determined to follow in very small steps and precise actions.

  1. I downloaded a zip of my current hacky site for safekeeping. (Yes, a zip. No, I don't want to risk mucking around among branches. Been there.)
  2. I went through AS's files and folder structure, with close attention to the .yml file contents.
  3. I stripped down AS's version to just have Week 1's stuff, and deleted the rest of the content - images, .md files, etc - from other weeks. This lightened the size of the entire folder set since I didn't want this initialization to be too big in terms of size. I was left with just the basics - index, about, project.
  4. I had earlier manually deleted and uploaded files into the repo using the web IDE. However, the 'upload' function does not upload folders, only files. Creating folders at every level before uploading their files was tedious. Knowing that I had to use Git directly, I finally just used the GitLab GUI to clone my repo to the harddisk. I pasted over the repo files with AS's minimal version, replicating the folder structure and keeping only my about.md and index.md files.
  5. On GitGUI, I scanned, staged and committed the changes.
  6. Lo-and-behold, the GitLab pipeline was successful and my website was suddenly taken over by Adam Stone ! You'd think that this was it and I was done, but HAH. I was only halfway there.
  7. I copied over and replicated the rest of my files into the repo, and committed. Unfortunately, the GitGUI default branch is not Main, like the website, but Master. This resulted in a second branch to be created, and now I had a Main and a Master. I tried renaming the branch in GitGUI but nothing worked. I had done this earlier in the same session but then I had gone and merged the two. However, I knew I did not want to be fielding merge requests every time I committed simply because of a naming error.
  8. So I deleted the entire folder, and cloned it again. This time I overwrote it with my entire folder structure and files, while editing the mkdocs.yml and generally keeping AS's "system" files. No dice. Pipeline failed.
  9. Delete. Re-clone. Now I was determined to make minimal changes. I overwrote my repo with AS's files, but only the ymls and the requirements.txt. Things worked again, the pipeline was successful.
  10. Edited the mkdocs yml file manually and committed. Worked again. Some relief.
  11. Step by step, I kept changing the mkdocs yml from AS's original to my version. I was being very careful to isolate what was breaking the pipeline. However, everything seemed to work. I eventually got over my Weekly MD files and the rest of my structure.
  12. As a last set of steps, I played around with a few themes now that things were working and came back to the default readthedocs theme from the ivory that I had chosen.

The pipeline is near instantaneous when dealing with non-YML files. When .yml files are edited, it takes a few minutes. I was at approximately 48-odd commits now, almost half of which had been today itself, from the multiple upload-delete-clone-update sequences. Thankfully, repo size was in the mid-20 MBs. I hadn't added any images yet though.

Resizing Images in MKDocs

Once I was reasonably sure that the pipeline was working, my .md files were all upped-and-loaded, and generally things were fine, I decided to clean up my images workflow. But first, I needed to resize the images on the page.

I had run through a lot of online resources, and had come to the following conclusions : 1. markdown allows images, ofcourse, but you can't resize theme 2. to set images with a particular size, you need to use raw HTML tags to embed images and specify width, height attributes

I tried various ways of defining the HTML tag (there's only so many ways to write ) but nothing seemed to work. Finally, I had every option in the code and I sent a screenshot with an appeal to help to the Regional Whatsapp group.

Deepu responded in a bit, with something that seemed to work for him. Unfortunately, it didn't for me. I suspected he had other plugins or extensions active, having seen that such things exist from AS's mkdocs.yml as well as all my adventures in getting MkDocs to work earlier. Deepu very kindly sent me a picture of his mkdocs.yml file and there was something there that seemed to fit the bill - an extension called list_attr.

I looked it up and added it to my yml file, and Lo and Behold, my images resized !

Images workflow

While free tools and CLI has been recommended, I already have a documentation workflow atleast as far as images and visuals are concerned, that I use for my main website, social media, etc. I worked out one for the FabAcademy documentation along similar lines. Admittedly, I will be using a non-FOSS software for this, but I don't see any benefit to changing my workflow - and potentially my storage and organization structures - for this.

A change I am making is this, though;
Usually, the documentation time frame is not critical, so I download pictures from my cellphone and camera at longer intervals. For the FabAcademy documentation, though, things have always been last-minute, or atleast fast-paced. I've been using Telegram to quickly move images from cellphone to laptop, for the most part. However, the images are of reduced size and quality (even with Telegram, not Whatsapp) and anyway, I'd like to organize the original pictures rather than derivatives.
So I setup a google drive folder that I can keep sending pictures to, and it will keep syncing with a corresponding folder on the laptop, and the folder is scanned by my library manager and new images are imported. This speeds up the transfer process, which is the bottleneck, and I can proceed with my usual workflow from here. The only issues that I need to address soon, is that when I sync ALL my cellphone images, as I would periodically, this would leave me with double copies to manually delete.

Things I learnt

  • Images can't be resized in markdown.
  • Unless you use an extension called List Attributes (list_attr) Attribute Lists
  • Double spaces at the end of a line are a really effective new-line break in markdown.
  • Careful with the branch and repo names.
  • Clean up your assorted files and folders for clarity and ease of use, now or later.

Updates

I found the following resources very useful

Markdown Guide - Basic Syntax for general formatting whenever I needed clarity. Markdown Guide - Extended Syntax for creating tables and such-like. Szymon Krajewski for the 2 spaces = new line nugget.

Embed videos in MKDOcs

https://pypi.org/project/mkdocs-video/ https://fabacademy.org/2022/labs/kannai/Instruction/tips/embed_videos/