Skip to content

Commit 441a13d

Browse files
steven-noorbergensteven-noorbergen
authored
Chore: Rework documentation layout using mkdocs (#86)
* Chore: Rework documentation layout using mkdocs * Fix: Address some feedback from @TrueBrain and clean up the .gitignore a lot * Minor tweaks based on feedback from @Dusty-Meg and @kennethjor
1 parent 011fab4 commit 441a13d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+917
-3070
lines changed

‎.github/dependabot.yml

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: pip
4+
# We only want to bump versions of packages in case of security updates, as
5+
# we want to keep maximum compatibility - see https://t.ly/INSR_
6+
open-pull-requests-limit: 0
7+
directory: "/"
8+
labels: []
9+
schedule:
10+
interval: weekly
11+
time: "08:00"
12+
- package-ecosystem: github-actions
13+
open-pull-requests-limit: 10
14+
directory: "/"
15+
labels: []
16+
schedule:
17+
interval: weekly
18+
time: "08:00"

‎.github/workflows/ci.yml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: tests
2+
on:
3+
pull_request:
4+
branches:
5+
- main
6+
7+
env:
8+
PYTHON_VERSION: 3.x
9+
10+
jobs:
11+
build:
12+
name: Build documentation
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Setup python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: ${{ env.PYTHON_VERSION }}
22+
cache: pip
23+
cache-dependency-path: |
24+
requirements.txt
25+
26+
- name: Install dependencies
27+
run: make init
28+
29+
- name: Build documentation with strict mode
30+
run: make test

‎.github/workflows/documentation.yml

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: documentation
2+
on:
3+
push:
4+
branches:
5+
- main
6+
7+
env:
8+
PYTHON_VERSION: 3.x
9+
10+
permissions:
11+
contents: write
12+
id-token: write
13+
pages: write
14+
15+
jobs:
16+
documentation:
17+
name: Build documentation
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- name: Setup python ${{ env.PYTHON_VERSION }}
24+
uses: actions/setup-python@v5
25+
with:
26+
python-version: ${{ env.PYTHON_VERSION }}
27+
cache: pip
28+
cache-dependency-path: |
29+
requirements.txt
30+
31+
- name: Install dependencies
32+
run: make init
33+
34+
- name: Build documentation
35+
run: make build
36+
37+
- name: Configure AWS Credentials if S3 deploying is enabled
38+
# Giving this step a name so we can check later if we need to deploy to GitHub Pages instead.
39+
id: using-s3
40+
if: ${{ env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY && env.AWS_S3_BUCKET && env.AWS_REGION }}
41+
uses: aws-actions/configure-aws-credentials@v4
42+
with:
43+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
44+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
45+
aws-region: ${{ secrets.AWS_REGION }}
46+
env:
47+
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
48+
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
49+
AWS_REGION: ${{ secrets.AWS_REGION }}
50+
AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
51+
52+
- name: Push to S3 if enabled
53+
if: ${{ steps.using-s3.conclusion == 'success' }}
54+
run: aws s3 sync ./site/ s3://${{ secrets.AWS_S3_BUCKET }} --delete
55+
env:
56+
AWS_REGION: ${{ secrets.AWS_REGION }}
57+
AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
58+
59+
- name: Prepare GitHub Pages artifact if not deploying to S3
60+
if: ${{ steps.using-s3.conclusion == 'skipped' }}
61+
uses: actions/upload-pages-artifact@v3
62+
with:
63+
path: site
64+
65+
- name: Deploy to GitHub Pages
66+
if: ${{ steps.using-s3.conclusion == 'skipped' }}
67+
continue-on-error: true
68+
uses: actions/deploy-pages@v4

‎.gitignore

+5-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
1-
.venv
2-
__pycache__
1+
.env
2+
.venv/
3+
/site/
4+
/.cache/
5+
/.idea/

‎.vscode/extensions.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"recommendations": [
3+
"GitHub.copilot",
4+
"bierner.markdown-mermaid",
5+
"esbenp.prettier-vscode",
6+
"redhat.vscode-yaml"
7+
]
8+
}

‎.vscode/launch.json

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "Local development",
6+
"type": "debugpy",
7+
"request": "launch",
8+
"program": "${workspaceRoot}/.venv/bin/mkdocs",
9+
"args": ["serve"],
10+
"serverReadyAction": {
11+
"pattern": "Serving on (https?://.+)",
12+
"uriFormat": "%s",
13+
"action": "openExternally"
14+
}
15+
}
16+
]
17+
}

‎.vscode/settings.json

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"editor.tabSize": 4,
3+
"editor.formatOnSave": true,
4+
"editor.inlineSuggest.enabled": true,
5+
"typescript.validate.enable": true,
6+
"javascript.validate.enable": true,
7+
"[json]": {
8+
"editor.tabSize": 2,
9+
"editor.defaultFormatter": "esbenp.prettier-vscode"
10+
},
11+
"[jsonc]": {
12+
"editor.tabSize": 2,
13+
"editor.defaultFormatter": "esbenp.prettier-vscode"
14+
},
15+
"[css]": {
16+
"editor.tabSize": 2
17+
},
18+
"[scss]": {
19+
"editor.tabSize": 2
20+
},
21+
"[javascript]": {
22+
"editor.tabSize": 2,
23+
"editor.defaultFormatter": "esbenp.prettier-vscode"
24+
},
25+
"[javascriptreact]": {
26+
"editor.tabSize": 2,
27+
"editor.defaultFormatter": "esbenp.prettier-vscode"
28+
},
29+
"[typescript]": {
30+
"editor.tabSize": 2,
31+
"editor.defaultFormatter": "esbenp.prettier-vscode"
32+
},
33+
"[typescriptreact]": {
34+
"editor.tabSize": 2,
35+
"editor.defaultFormatter": "esbenp.prettier-vscode"
36+
},
37+
"[html]": {
38+
"editor.tabSize": 2
39+
},
40+
"[markdown]": {
41+
"editor.tabSize": 4
42+
},
43+
"[yaml]": {
44+
"editor.tabSize": 2
45+
},
46+
"[github-actions-workflow]": {
47+
"editor.tabSize": 2
48+
},
49+
// Tabs should be spaces.
50+
"editor.insertSpaces": true,
51+
"workbench.colorCustomizations": {
52+
"titleBar.activeForeground": "#000000",
53+
"titleBar.inactiveForeground": "#cccccc",
54+
"titleBar.activeBackground": "#ff9925",
55+
"titleBar.inactiveBackground": "#341f00"
56+
}
57+
}

‎Makefile

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.PHONY: init serve
2+
SHELL := /bin/bash
3+
4+
init:
5+
python3 -m venv .venv
6+
source .venv/bin/activate && pip install -r requirements.txt
7+
8+
serve:
9+
source .venv/bin/activate && mkdocs serve
10+
11+
build:
12+
source .venv/bin/activate && mkdocs build --clean
13+
14+
test:
15+
source .venv/bin/activate && mkdocs build --strict --clean

0 commit comments

Comments
 (0)