The existing Documentation¶

Design and Content Principles¶

Before we dive into the technical details, we need to define some principles that will guide our work:

• (Do not Repeat Yourself) DRY principle shall be followed as much as possible; cost-benefit trade-offs migh be necessary, in principle, changes in one place shall propagate everywhere else, ideally with no manual interaction
• we want to minimise the number or platforms/outlets
• a consistent look and feel shall be achieved
• ideally, design-aspects are inherited by several 'outlets'
• cer-documentation: researcher-facing, mostly detailed how-to-guides, with a very clear target-audience
  • IDS-documentation: Will be a sub-section? researcher-facing, mostly detailed how-to-guides, with a very clear target-audience
  • IDS-reference: developer-facing, a docstring-based autogenerated reference material
• there should be an experienced user overview and then collapsible boxes for the details

Some theory¶

Based on Noel's link and the resulting Youtube talk, there are four types of documentation:

Most of what we will do is 'how-to-guides'.

Game Plan¶

• Scan what documentation we have, remove/adjust/add if gap is identified
• what do we have/want
• who is responsible for
  • creating/updating content
  • approving
• Agree on a structure
• what what is parent-child?
• what terminology?

LINK TO THE EXCEL SHEET - add one template for emails that needs to update and then be fed into the CLI eres drive allocation notice project_groups.json

flowchart TD
    A[Wesbite]
    B[ResHub] -->|links to| F[cer-documentation]
    C[Nuclino] -->|CONNECT accessible | X[Wiki]
    C -->|e.g. HR tuts.| D[MSTeams]
    E[VMHandbook] -->|filtered/upated| F  

Simple charts¶

These few lines of code generate the chart below.

flowchart TD
    A[Wesbite]
    B[ResHub] -->|links to| F[cer-documentation]
    C[Nuclino] -->|CONNECT accessible | X[Wiki]
    C -->|e.g. HR tuts.| D[MSTeams]
    E[VMHandbook] -->|filtered/upated| F  

flowchart TD
    A[Wesbite]
    B[ResHub] -->|links to| F[cer-documentation]
    C[Nuclino] -->|CONNECT accessible | X[Wiki]
    C -->|e.g. HR tuts.| D[MSTeams]
    E[VMHandbook] -->|filtered/upated| F  

Questions¶

• how to make design inheritable across GHRepos
• how to link md files several times (DRY principle) but not having to manually create a navigation?
• maybe a blog
• or replace
• do we want to switch operating systems (similar to a langnage switcher)?
• where to include ToCs
• how to have collapsible boxes
• where to store video? Youtube vs. x
• where to store training material
• DReSA (mostly Australia-focused)
• Figshare (get DOI but have to revision a lot?)
• Panopto (hard to link to, as part of Canvas/SSO?)
• how to get a broken link checker

Why MKDocs Material is cool:¶

• language switcher planned misuse for win/osx/linux?

we can get tabs¶

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

Admonitions aka Call-Outs¶

Types to select from¶

Types

For a lot of how-to-guides, you need to let users know what keys to press. There is the <kbd> tag, but by including pymdownx.keys we can make our lives easier: Some examples, fenced by the ++ characters:

• Ctrl+Alt+Del
• Cmd+Fn+Del
• Left Button
• Middle Button

• Right Button

• Up

• Down
• Left
• Right
• Page Up
• Page Down
• Home
• End
• Tab

To add a custom label, you simply include this with double inverted commas

My Text

Code Annotation Examples¶

Codeblocks¶

Some code goes here.

Plain codeblock¶

A plain codeblock:

Some code here
def myfunction()
// some comment

Code for a specific language¶

Some more code with the py at the start:

import tensorflow as tf
def whatever()

With a title¶

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

With line numbers¶

1
2
3
4
5

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Highlighting lines¶

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Icons and Emojs¶

An efficient way of finding fonts in the correct syntax is to use this website

([How to set up Material for MkDocs] by @james-willett)[https://youtu.be/Q-YA_dA8C20?si=Zss-tTEUY2fdGkxI] – 15m – Learn how to create and host a documentation site using Material for MkDocs on GitHub Pages in a step-by-step guide.

How to use Icons¶

• MKDocs comes with a lot of icons
• they are in the theme folder ../venv/lib/python3.11/site-packages/material/templates/.icons/
• an efficient way to find the icon you want is to check this website
• to use them, you need to adapt the syntax a bit:
• for example: you would find

• switch.my_switch:
  friendly_name: My Switch
  icon: mdi:account-arrow-down-outline
  

• and you will use the following part of the last line: account-arrow-down-outline, this gets the prefix material- and is fenced by the : character before and after. So you write this code :material-account-arrow-down-outline:
• to get this icon

Using Variable¶

My name is John Doe the definition of the variables go in the mkdocs.yml file yaml hl_lines="3"

Including images¶

• images are stored in the assets folder
• VSC can provide a relative link
• the syntax is ![useful image](./assets/myimage.jpg)
• you can also use the :width="50%" to resize the image
• you can also use the hash fragments to make screenshots appear only in light or dark mode
  • #only-light)
  • see example below

• If we feel the need for a slide-show, we can have a look at glightbox
• We could also try to integrate a Python-based Macro to automatically add a lot of configurations (size, dark/light, alignment left, right, caption, ...)
• If we need captions, Markdown doesn't support that natively, so we'd have to use html

Capturing Screen Shots¶

On a Mac¶

Cmd+Shift+4 then Space (to select just the window) then while holding Option you click which stores it in the default location

Expanding content¶

• collapsible boxes (see above)
• this is also an example of how to reference another section in the same document. Lowercase and hypen instead of spaces. Easy to get this is to load the final documentation. Click the link generation. Copy from the browser URL bar.
• annotations

Embedding Video¶

• might have to go to Youtube because can't be shared from GDrive
• Panopto won't work either, because one has to log in to Canvas
• https://streamable.com/ is mentioned as a common alternative
• not sure if Dropbox would work

One example here

Adding tool tips or abbreviations¶

We can just type out text as per the usual with some acronyms. But as we use *[TLA]: Three Letter Acronym below this isn't shown but once we hover over the text in question, a tip shows up

The HTML specification is maintained by the W3C.

We can also add this to icons

Efficiently Capturing Screen Shots¶

Install this VSC Extension and adjust the settings as shown in the screen shot below. Afterwards, you can just paste images (take screen shot on MacOS Cmd+Ctrl+Shift+4) into your markdown file by pressing Cmd+Option+V and they will be automatically saved in the assets folder and linked to the markdown file.

Capturing one window on MacOS¶

After pressing Cmd+Ctrl+Shift+4, press Space and then left-click on the window you want to capture. This will automatically just take a screen shot of the active window which is indicated by the icon. As per the default, this also includes a drop shadow. You can also remove this shadow by pressing Option after you pressed Space but before left-clicking.