Skip to content

Commit 444d5f3

Browse files
RemoteRabbitRemoteRabbit
authored
feat: Create base mkdocs site with stubs and some tf vars I already w… (#4)
## Summary Base setup with stubs for some boilerplate pages site using mkdocs ## ✨ Features - Create base mkdocs site with stubs and some tf vars I already was working on [`d4a84bb`](d4a84bb) ## 🐛 Bug Fixes - remove example link since this is first build [`07b1e06`](07b1e06) - remove old mailto in lychee setup [`93f6c44`](93f6c44) - root-dir for lychee [`643ec7f`](643ec7f) ## 💄 Style - remove newline from svg port [`f8a7827`](f8a7827) ## 📁 File Changes ### Root (+1378/-0 lines) - `.gitignore` (+19) ✨ - `.markdownlint.yaml` (+24) ✨ - `.pre-commit-config.yaml` (+34) ✨ - `.yamllint` (+22) ✨ - `Makefile` (+107) ✨ - `lychee.toml` (+31) ✨ - `mkdocs.yml` (+202) ✨ - `pyproject.toml` (+33) ✨ - `uv.lock` (+906) ✨ ### .github (+147/-0 lines) - `.github/workflows/ci.yml` (+34) ✨ - `.github/workflows/deploy.yml` (+59) ✨ - `.github/workflows/links.yml` (+54) ✨ ### Documentation (+1786/-0 lines) - `README.md` (+52) 📝 - `docs/api/error-responses.md` (+15) ✨ - `docs/api/fastapi-skeleton.md` (+17) ✨ - `docs/api/go-chi-skeleton.md` (+16) ✨ - `docs/api/index.md` (+13) ✨ - `docs/api/openapi.md` (+15) ✨ - `docs/api/pagination.md` (+16) ✨ - `docs/assets/apple-touch-icon.png` ✨ - `docs/assets/extra.css` (+230) ✨ - `docs/assets/favicon-96x96.png` ✨ - `docs/assets/favicon.ico` ✨ - `docs/assets/favicon.svg` (+1) ✨ - `docs/assets/icon-192.png` ✨ - `docs/assets/icon-512.png` ✨ - `docs/assets/logo.svg` (+5) ✨ - `docs/containers/compose-dev.md` (+15) ✨ - `docs/containers/distroless.md` (+15) ✨ - `docs/containers/dockerfile-go.md` (+15) ✨ - `docs/containers/dockerfile-node.md` (+15) ✨ - `docs/containers/dockerfile-python.md` (+16) ✨ - `docs/containers/index.md` (+13) ✨ - `docs/data/airflow-dag.md` (+16) ✨ - `docs/data/alembic-skeleton.md` (+16) ✨ - `docs/data/dbt-skeleton.md` (+16) ✨ - `docs/data/index.md` (+13) ✨ - `docs/data/postgres-conventions.md` (+16) ✨ - `docs/data/postgres-indexes.md` (+16) ✨ - `docs/examples/code-blocks.md` (+356) ✨ - `docs/github-actions/container-build.md` (+16) ✨ - `docs/github-actions/index.md` (+13) ✨ - `docs/github-actions/oidc-aws.md` (+16) ✨ - `docs/github-actions/oidc-gcp-azure.md` (+15) ✨ - `docs/github-actions/path-filtered-matrix.md` (+15) ✨ - `docs/github-actions/release.md` (+15) ✨ - `docs/github-actions/reusable-workflows.md` (+15) ✨ - `docs/hygiene/editorconfig.md` (+13) ✨ - `docs/hygiene/gitignore.md` (+17) ✨ - `docs/hygiene/index.md` (+13) ✨ - `docs/hygiene/makefile.md` (+16) ✨ - `docs/hygiene/pre-commit.md` (+16) ✨ - `docs/index.md` (+101) ✨ - `docs/kubernetes/deployment-baseline.md` (+15) ✨ - `docs/kubernetes/helm-skeleton.md` (+16) ✨ - `docs/kubernetes/index.md` (+13) ✨ - `docs/kubernetes/probes.md` (+16) ✨ - `docs/kubernetes/rbac.md` (+16) ✨ - `docs/kubernetes/scaling.md` (+15) ✨ - `docs/observability/index.md` (+13) ✨ - `docs/observability/opentelemetry.md` (+16) ✨ - `docs/observability/prometheus.md` (+16) ✨ - `docs/observability/structured-logging.md` (+16) ✨ - `docs/terraform/backends.md` (+16) ✨ - `docs/terraform/iam-policies.md` (+16) ✨ - `docs/terraform/index.md` (+45) ✨ - `docs/terraform/module-skeleton.md` (+17) ✨ - `docs/terraform/providers.md` (+16) ✨ - `docs/terraform/variables.md` (+279) ✨ - `docs/terragrunt/index.md` (+14) ✨ - `docs/terragrunt/root-config.md` (+16) ✨ - `docs/terragrunt/stacks.md` (+16) ✨ --- **Changes:** 72 files, +3311 insertions, -0 deletions **Commits:** 5 **Branch:** `feat/mkdocs-setup-stubbed` **Base:** `origin/main`
1 parent 1dba94b commit 444d5f3

72 files changed

Lines changed: 3311 additions & 0 deletions

Some content is hidden

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

‎.github/workflows/ci.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
lint-and-build:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
with:
17+
fetch-depth: 0
18+
19+
- uses: astral-sh/setup-uv@v4
20+
with:
21+
enable-cache: true
22+
cache-dependency-glob: uv.lock
23+
24+
- name: Set up Python
25+
run: uv python install 3.12
26+
27+
- name: Install dependencies
28+
run: uv sync --frozen
29+
30+
- name: Run pre-commit
31+
run: uv run pre-commit run --all-files --show-diff-on-failure
32+
33+
- name: Build site (strict + htmlproofer)
34+
run: uv run mkdocs build --strict

‎.github/workflows/deploy.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Deploy site to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- 'mkdocs.yml'
9+
- 'pyproject.toml'
10+
- 'uv.lock'
11+
- '.github/workflows/deploy.yml'
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
concurrency:
20+
group: pages
21+
cancel-in-progress: false
22+
23+
jobs:
24+
build:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0 # needed for git-revision-date-localized
30+
31+
- uses: astral-sh/setup-uv@v4
32+
with:
33+
enable-cache: true
34+
cache-dependency-glob: uv.lock
35+
36+
- name: Set up Python
37+
run: uv python install 3.12
38+
39+
- name: Install dependencies
40+
run: uv sync --frozen --no-dev
41+
42+
- name: Build site
43+
run: uv run mkdocs build --strict
44+
45+
- uses: actions/configure-pages@v5
46+
47+
- uses: actions/upload-pages-artifact@v3
48+
with:
49+
path: site
50+
51+
deploy:
52+
needs: build
53+
runs-on: ubuntu-latest
54+
environment:
55+
name: github-pages
56+
url: ${{ steps.deployment.outputs.page_url }}
57+
steps:
58+
- id: deployment
59+
uses: actions/deploy-pages@v4

‎.github/workflows/links.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Link check
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docs/**'
7+
- 'README.md'
8+
- 'lychee.toml'
9+
- '.github/workflows/links.yml'
10+
schedule:
11+
- cron: '0 8 * * 1' # Mondays 08:00 UTC
12+
workflow_dispatch:
13+
14+
permissions:
15+
contents: read
16+
issues: write # for the scheduled run that opens an issue on failure
17+
18+
jobs:
19+
lychee:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
24+
- name: Restore lychee cache
25+
uses: actions/cache@v4
26+
with:
27+
path: .lycheecache
28+
key: cache-lychee-${{ github.sha }}
29+
restore-keys: cache-lychee-
30+
31+
- name: Run lychee
32+
id: lychee
33+
uses: lycheeverse/lychee-action@v2
34+
with:
35+
args: >-
36+
--config lychee.toml
37+
--cache
38+
--max-cache-age 7d
39+
--root-dir ${{ github.workspace }}
40+
'docs/**/*.md'
41+
'README.md'
42+
fail: ${{ github.event_name == 'pull_request' }}
43+
format: markdown
44+
output: lychee-report.md
45+
46+
# On the weekly schedule, file a tracking issue on failure rather than
47+
# failing the workflow loudly. PR runs already gate via `fail: true` above.
48+
- name: Open issue on scheduled failure
49+
if: ${{ github.event_name == 'schedule' && steps.lychee.outputs.exit_code != 0 }}
50+
uses: peter-evans/create-issue-from-file@v5
51+
with:
52+
title: Broken links found by lychee
53+
content-filepath: lychee-report.md
54+
labels: link-rot, automated

‎.gitignore‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Built site
2+
/site/
3+
4+
# Python / uv
5+
.venv/
6+
__pycache__/
7+
*.pyc
8+
.ruff_cache/
9+
.mypy_cache/
10+
.cache/
11+
12+
# Tool caches
13+
.lycheecache
14+
lychee-report.md
15+
16+
# Editors / OS
17+
.DS_Store
18+
.idea/
19+
.vscode/

‎.markdownlint.yaml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
3+
default: true
4+
5+
# Line length — match other linters at 120, ignore code blocks/tables.
6+
MD013:
7+
line_length: 120
8+
code_blocks: false
9+
tables: false
10+
headings: false
11+
12+
# Allow inline HTML (admonitions, <details>, etc. used by MkDocs Material).
13+
MD033: false
14+
15+
# Allow duplicate headings under different parents (common in nav-heavy docs).
16+
MD024:
17+
siblings_only: true
18+
19+
# Don't require first line to be a top-level heading (MkDocs uses page titles
20+
# from nav).
21+
MD041: false
22+
23+
# Bare URLs are fine; magiclink turns them into proper links.
24+
MD034: false

‎.pre-commit-config.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
repos:
3+
- repo: https://github.com/pre-commit/pre-commit-hooks
4+
rev: v5.0.0
5+
hooks:
6+
- id: trailing-whitespace
7+
exclude: ^site/
8+
- id: end-of-file-fixer
9+
exclude: ^site/
10+
- id: check-merge-conflict
11+
- id: check-added-large-files
12+
args: [--maxkb=500]
13+
- id: mixed-line-ending
14+
args: [--fix=lf]
15+
- id: check-yaml
16+
# `--unsafe` lets MkDocs Material use !!python/name: and similar tags.
17+
args: [--unsafe]
18+
- id: check-toml
19+
- id: check-json
20+
21+
- repo: https://github.com/codespell-project/codespell
22+
rev: v2.3.0
23+
hooks:
24+
- id: codespell
25+
additional_dependencies: ["tomli"]
26+
27+
- repo: local
28+
hooks:
29+
- id: mkdocs-build
30+
name: mkdocs build (strict)
31+
entry: uv run mkdocs build --strict --quiet
32+
language: system
33+
pass_filenames: false
34+
files: ^(docs/|mkdocs\.yml|pyproject\.toml)

‎.yamllint‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
extends: default
3+
4+
rules:
5+
line-length:
6+
max: 120
7+
level: warning
8+
truthy:
9+
# Allow GitHub Actions' `on:` key.
10+
check-keys: false
11+
comments:
12+
min-spaces-from-content: 1
13+
document-start:
14+
present: true
15+
indentation:
16+
spaces: 2
17+
indent-sequences: true
18+
19+
ignore: |
20+
site/
21+
.venv/
22+
node_modules/

‎Makefile‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# boilplate — local dev convenience targets
2+
# Run `make help` to see what's available.
3+
#
4+
# All Python work is done through `uv`, which manages the .venv automatically.
5+
# Install uv: https://docs.astral.sh/uv/getting-started/installation/
6+
7+
UV ?= uv
8+
PORT ?= 8000
9+
VENV := .venv
10+
RUN := $(UV) run
11+
12+
.DEFAULT_GOAL := help
13+
14+
# ---- meta ------------------------------------------------------------------
15+
16+
.PHONY: help
17+
help: ## Show this help.
18+
@awk 'BEGIN {FS = ":.*##"; printf "\nUsage: \033[36mmake <target>\033[0m\n\nTargets:\n"} \
19+
/^[a-zA-Z0-9_.-]+:.*##/ { printf " \033[36m%-16s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
20+
@echo
21+
22+
.PHONY: check-uv
23+
check-uv:
24+
@command -v $(UV) >/dev/null 2>&1 || { \
25+
echo "error: 'uv' is not installed."; \
26+
echo " install it from https://docs.astral.sh/uv/getting-started/installation/"; \
27+
exit 1; \
28+
}
29+
30+
# ---- environment -----------------------------------------------------------
31+
32+
$(VENV): pyproject.toml
33+
$(UV) sync
34+
@touch $(VENV)
35+
36+
.PHONY: install
37+
install: check-uv $(VENV) ## Create .venv and install all dependencies (incl. dev).
38+
39+
.PHONY: lock
40+
lock: check-uv ## Refresh uv.lock from pyproject.toml.
41+
$(UV) lock
42+
43+
.PHONY: upgrade
44+
upgrade: check-uv ## Upgrade all dependencies to the latest allowed versions.
45+
$(UV) lock --upgrade
46+
$(UV) sync
47+
48+
# ---- docs ------------------------------------------------------------------
49+
50+
.PHONY: serve
51+
serve: install ## Run the docs site locally with live reload (http://localhost:$(PORT)).
52+
$(RUN) mkdocs serve -a 0.0.0.0:$(PORT)
53+
54+
.PHONY: build
55+
build: install ## Build the static site into ./site (strict mode + htmlproofer).
56+
$(RUN) mkdocs build --strict
57+
58+
.PHONY: links
59+
links: ## Run lychee link checker against docs/ and README. Requires lychee in PATH.
60+
@command -v lychee >/dev/null 2>&1 || { \
61+
echo "error: 'lychee' is not installed."; \
62+
echo " install it from https://lychee.cli.rs/installation/"; \
63+
exit 1; \
64+
}
65+
lychee --config lychee.toml --cache --max-cache-age 7d 'docs/**/*.md' README.md
66+
67+
# ---- quality ---------------------------------------------------------------
68+
69+
.PHONY: lint
70+
lint: install ## Run ruff lint.
71+
$(RUN) ruff check .
72+
73+
.PHONY: format
74+
format: install ## Format Python files with ruff.
75+
$(RUN) ruff format .
76+
$(RUN) ruff check --fix .
77+
78+
.PHONY: hooks
79+
hooks: install ## Install pre-commit git hooks.
80+
$(RUN) pre-commit install
81+
82+
.PHONY: pre-commit
83+
pre-commit: install ## Run all pre-commit hooks against every file.
84+
$(RUN) pre-commit run --all-files
85+
86+
# ---- terraform / opentofu --------------------------------------------------
87+
88+
.PHONY: tf-fmt
89+
tf-fmt: ## Format all Terraform / OpenTofu files in-tree.
90+
@command -v terraform >/dev/null 2>&1 && terraform fmt -recursive terragrunt || \
91+
(command -v tofu >/dev/null 2>&1 && tofu fmt -recursive terragrunt) || \
92+
(echo "neither terraform nor tofu is installed" >&2; exit 1)
93+
94+
.PHONY: tg-fmt
95+
tg-fmt: ## Format all Terragrunt HCL files in-tree.
96+
@command -v terragrunt >/dev/null 2>&1 || (echo "terragrunt is not installed" >&2; exit 1)
97+
terragrunt hcl format
98+
99+
# ---- housekeeping ----------------------------------------------------------
100+
101+
.PHONY: clean
102+
clean: ## Remove build artifacts and the virtualenv.
103+
rm -rf site $(VENV) .ruff_cache .cache
104+
105+
.PHONY: clean-site
106+
clean-site: ## Remove only the built site.
107+
rm -rf site

0 commit comments

Comments
 (0)