Skip to content

Commit ef7bece

Browse files
nomisnomis
authored
Merge pull request #15 from tcmal/risk-assessments
Code for generating risk assessments, templates for new tools, looks
2 parents 9b33c84 + 7684db8 commit ef7bece

23 files changed

+546
-127
lines changed

‎Justfile‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎README.md‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,35 @@
11
# hacklab-training
22

3-
Training syllabi for Edinburgh Hacklab
3+
Training syllabi for Edinburgh Hacklab.
44

5-
To build locally (using docker), run `just generate` (or `just open`).
6-
If messing with the code that does the generation, see [`generator/README.md`](./generator/README.md)
5+
If you're just looking for the content, see [training.ehlab.uk](https://training.ehlab.uk).
6+
7+
## Adding training
8+
9+
The training materials are generated from the markdown files in this repo, which are structured like this:
10+
11+
```
12+
└── syllabuses
13+
└── <Location, ie Workshop>
14+
├── <Tool, ie CNC Mill>
15+
│   ├── risk-assessment.md
16+
│   └── syllabus.md
17+
```
18+
19+
`syllabus.md` becomes the training doc, and each header becomes an item in the training card. Each level 2 (`##`) header in `risk-assessment.md` becomes a row in the risk assessment, and the subheaders are used to populate the columns.
20+
21+
To preview your built changes locally, run `./scripts/open.sh` or ``./scripts/generate.sh` from the root of the repo. This requires docker to be working - if this is a problem consider using `shell.ehlab.uk`. You can also add a case insensitive filter to the end of the command to speed things up, ie `./scripts/generate.sh workshop`
22+
23+
If you're adding a new tool, run `./scripts/new-tool.sh <tool name> <tool location>`, ie `./scripts/new-tool.sh "CNC Mill" "Workshop"`
24+
25+
If you want to mess with the code that does the generation, see [`generator/README.md`](./generator/README.md)
26+
27+
### Common pitfalls
28+
29+
- There may still be some cases where our generator doesn't escape special characters properly, which might break text containing any of: `\ % & $ # _ { } ~ ^`. If this seems to be the case, ask someone who's comfortable poking the generator to take a look.
30+
- When writing risk assessments, note that the subheaders need to have specific names in order to actually be included. These are case sensitive:
31+
- Severity
32+
- Likelihood
33+
- Risk rating
34+
- Who may be harmed & how
35+
- Control measures

‎generator/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@
22
*.egg-info
33
**/*.pyc
44
out/
5+
.cache

‎generator/Dockerfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ FROM python:3.12
22

33
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
44
ENV DEBIAN_FRONTEND=noninteractive
5-
RUN apt update && apt install -y texlive-latex-base texlive-latex-extra
5+
RUN apt update && apt install -y texlive-latex-base texlive-latex-extra texlive-fonts-extra
66

77
WORKDIR /app
88

‎generator/Dockerfile.dev‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@ RUN wget -qO - 'https://proget.makedeb.org/debian-feeds/prebuilt-mpr.pub' | gpg
66
. /etc/os-release && \
77
echo "deb [arch=all,$(dpkg --print-architecture) signed-by=/usr/share/keyrings/prebuilt-mpr-archive-keyring.gpg] https://proget.makedeb.org prebuilt-mpr $VERSION_CODENAME" | tee /etc/apt/sources.list.d/prebuilt-mpr.list
88

9-
RUN apt update && apt install -y texlive-latex-base texlive-latex-extra just
9+
RUN apt update && apt install -y texlive-latex-base texlive-latex-extra just texlive-fonts-extra
1010
RUN mkdir -p /home/dev && chmod 777 /home/dev

‎generator/Justfile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,5 @@ build-devcontainer:
1515
docker build . -t hacklab-training-generator-dev -f Dockerfile.dev
1616

1717
devcontainer:
18-
docker run -it --rm -v $PWD/..:/home/dev/src -w /home/dev/src/generator -u $(id -u):$(id -g) -e HOME=/home/dev/ hacklab-training-generator-dev bash
18+
mkdir -p .cache
19+
docker run -it --rm -v $PWD/.cache:/home/dev -v $PWD/..:/home/dev/src -w /home/dev/src/generator -u $(id -u):$(id -g) -e HOME=/home/dev/ hacklab-training-generator-dev bash

‎generator/assets/prelude.tex‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
\usepackage[top=2cm,left=2cm,right=2cm,bottom=2cm,headsep=0.25cm,nomarginpar]{geometry}
2+
\usepackage{enumitem}
3+
\usepackage{lastpage}
4+
\usepackage{graphicx}
5+
\usepackage{ltablex}
6+
\usepackage{colortbl}
7+
\usepackage[]{fancyhdr}
8+
\usepackage{titlesec}
9+
\usepackage[sfdefault]{inter}
10+
\keepXColumns
11+
12+
% Include a vertically centered graphic inline (used for footer)
13+
\newcommand{\vcenteredinclude}[2]{\begingroup
14+
\setbox0=\hbox{\includegraphics[#1]{#2}}%
15+
\parbox{\wd0}{\box0}\endgroup}
16+
17+
% Headers + footers
18+
\pagestyle{fancy}
19+
\fancyhead{}
20+
\fancyhead[L]{\large\textbf\docTool}
21+
\fancyhead[R]{\large\textbf\docType}
22+
\fancyfoot{}
23+
\fancyfoot[L]{\vcenteredinclude{height=0.75cm}{./assets/logo}\hspace{0.5em} training.ehlab.uk}
24+
\fancyfoot[R]{Version \docVersion, \thepage\ / \pageref{LastPage}}
25+
\renewcommand{\footrulewidth}{1pt}
26+
27+
% Typography
28+
\titleformat{\section}[block]
29+
{\normalfont\bfseries}
30+
{\thesection.}{0.5em}{}
31+
\titlespacing{\section}{0pt}{0.5em}{0.5em}
32+
\titleformat{\subsection}[block]
33+
{\normalfont}
34+
{\thesubsection.}{0.5em}{}
35+
\titlespacing{\subsection}{0pt}{0.5em}{0.5em}
36+
37+
% Spacing
38+
\renewcommand{\headrulewidth}{1pt}
39+
\renewcommand{\headruleskip}{0pt}
40+
\setlist{itemsep=0.25em, parsep=0.25em, topsep=0.25em, labelindent=\parindent}
41+
\renewcommand{\arraystretch}{1.2}

‎generator/templates/risk-assessment.j2.tex‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
\documentclass[a4paper,landscape]{article}
2+
\newcommand{\docTool}{\VAR{title}}
3+
\newcommand{\docType}{Risk assessment}
4+
\newcommand{\docVersion}{\VAR{version}}
5+
\input{assets/prelude}
6+
7+
\setlength\parindent{0pt}
8+
\usepackage{xcolor}
9+
\newcommand*\rot{\rotatebox{90}}
10+
11+
\begin{document}
12+
13+
This table outlines the possible risks that users of this tool should bear in mind. The risk rating, likelihood, and severity are all calculated assuming that the listed control measures are followed.
14+
If you are uncomfortable with these risks, or are not confident in your ability to use this tool safely, please do not use it.
15+
16+
\vspace{1em}
17+
18+
\begin{tabularx}{\textwidth}{@{}r @{\hspace{3pt}} l|l|l|l|l|X}
19+
& \rot{Risk rating} & \rot{Likelihood} & \rot{Severity} & Hazard & Who may be harmed \& how & Control measures \\
20+
\endhead
21+
\BLOCK{for item in items}
22+
\hline
23+
24+
25+
\BLOCK{set values = namespace(riskrating='?', likelihood='?', severity='?', who = '?', control='?')}
26+
27+
\BLOCK{for subitem in item.items}
28+
\BLOCK{if subitem.name == 'Risk rating' }
29+
\BLOCK{set values.riskrating = subitem.text}
30+
\BLOCK{elif subitem.name == 'Likelihood' }
31+
\BLOCK{set values.likelihood = subitem.text}
32+
\BLOCK{elif subitem.name == 'Severity' }
33+
\BLOCK{set values.severity = subitem.text}
34+
\BLOCK{elif 'Who may be harmed' in subitem.name }
35+
\BLOCK{set values.who = subitem.text}
36+
\BLOCK{elif subitem.name == 'Control measures' }
37+
\BLOCK{set values.control = subitem.text}
38+
\BLOCK{endif}
39+
\BLOCK{endfor}
40+
41+
\BLOCK{if values.riskrating == 'H'}
42+
\BLOCK{set barcolor = 'red'}
43+
\BLOCK{elif values.riskrating == 'M'}
44+
\BLOCK{set barcolor = 'orange'}
45+
\BLOCK{elif values.riskrating == 'L'}
46+
\BLOCK{set barcolor = 'yellow'}
47+
\BLOCK{else}
48+
\BLOCK{set barcolor = 'black'}
49+
\BLOCK{endif}
50+
51+
{\color{\VAR{barcolor}}\vrule width 3pt} & \VAR{values.riskrating} &\VAR{values.likelihood} & \VAR{values.severity} & \VAR{item.name} & \VAR{values.who} & \VAR{values.control} \\
52+
\BLOCK{endfor}
53+
54+
\end{tabularx}
55+
56+
\end{document}

‎generator/templates/risk-assessment.md.tmpl‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# $TOOL
2+
3+
<!-- Each thing below becomes a row in the table - copy it for each risk that's been identified.
4+
Please delete all the comments from the final document -->
5+
6+
## A thing that might go wrong
7+
8+
### Severity
9+
10+
<!-- How bad it is if the thing happens. H, M, or L. -->
11+
H
12+
13+
### Likelihood
14+
15+
<!-- How likely something is, *after* the control measures listed below. H, M, or L. -->
16+
H
17+
18+
### Risk rating
19+
20+
<!-- If both likelihood and severity are H, this is H
21+
If one of likelihood and severity is L, and the other is L or M, this is L
22+
Otherwise, this is M -->
23+
H
24+
25+
### Who may be harmed & how
26+
27+
<!-- Usually some combination of:
28+
User
29+
Bystander
30+
Users of the room
31+
The space
32+
Following user -->
33+
34+
### Control measures
35+
36+
<!-- Anything that's in here should also be in the syllabus somewhere, to ensure it's actually practised. -->

‎generator/templates/syllabus.md.tmpl‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# $TOOL
2+
3+
<!-- There is no prescribed structure, but here is a suggestion: -->
4+
5+
## Safety
6+
7+
### PPE
8+
9+
### Risks
10+
11+
<!-- Usually, all of the control measures in the risk assessment should be mentioned here -->
12+
13+
## Startup checks
14+
15+
## Usage
16+
17+
### Starting the machine
18+
19+
### Stopping the machine
20+
21+
<!-- incl estops if necessary -->
22+
23+
### General
24+
25+
### Materials
26+
27+
### Cleaning up
28+
29+
## Maintenance
30+
31+
### General
32+
33+
## Other

0 commit comments

Comments
 (0)