From bad61bea2d75538ba0d8c850dbacaef91946de3e Mon Sep 17 00:00:00 2001 From: disqualifier Date: Mon, 29 Jun 2026 19:29:30 -0400 Subject: [PATCH] scaffold MkDocs Material handbook site Initialize the public Rethink Studios docs site: - mkdocs.yml: Material theme, light/dark palette toggle, pymdownx extensions, search, four-section nav skeleton. - docs/index.md landing page with a card grid. - Stub index pages for deploy, conventions, libraries, runbooks. - .gitignore excludes .claude/, site/, and Python build cruft. Deploy guide deferred; deploy section is a placeholder for now. Signed-off-by: disqualifier --- .gitignore | 11 +++++++ docs/conventions/index.md | 19 +++++++++++ docs/deploy/index.md | 22 +++++++++++++ docs/index.md | 46 ++++++++++++++++++++++++++ docs/libraries/index.md | 23 +++++++++++++ docs/runbooks/index.md | 17 ++++++++++ mkdocs.yml | 69 +++++++++++++++++++++++++++++++++++++++ 7 files changed, 207 insertions(+) create mode 100644 .gitignore create mode 100644 docs/conventions/index.md create mode 100644 docs/deploy/index.md create mode 100644 docs/index.md create mode 100644 docs/libraries/index.md create mode 100644 docs/runbooks/index.md create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9e8a729 --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +# Claude project scaffold — never committed +.claude/ + +# MkDocs build output +site/ + +# Python +__pycache__/ +*.py[cod] +.venv/ +venv/ diff --git a/docs/conventions/index.md b/docs/conventions/index.md new file mode 100644 index 0000000..ba99e81 --- /dev/null +++ b/docs/conventions/index.md @@ -0,0 +1,19 @@ +# Conventions + +Coding, library, and infrastructure conventions that keep projects consistent. + +!!! note "Work in progress" + Individual convention pages will be added under this section and wired into + the nav. + +## Topics to document + +- **Python style** — flake8 clean (max line 120), type hints on public + functions, lowercase-start docstrings with no trailing period. +- **Library layout** — `src/` layout, hatchling, Python ≥ 3.10, underscores in + names, `aio`-prefix only for libs that define async surfaces. +- **Logging** — emit-only in libraries (`logging.getLogger(__name__)`); handler, + level, and format configured only at the application entry point. +- **Files** — trailing newline, no trailing whitespace, LF line endings. +- **Config** — config-free modules (inject dependencies), single source of + truth, no duplicated logic or constants. diff --git a/docs/deploy/index.md b/docs/deploy/index.md new file mode 100644 index 0000000..2eefdd6 --- /dev/null +++ b/docs/deploy/index.md @@ -0,0 +1,22 @@ +# Deploy + +Guides for getting a service from a repo to running behind the reverse proxy. + +!!! note "Work in progress" + The services-container deploy guide will live here. Until it's added, this + page is a placeholder. + +## Planned guides + +- **Services container standard** — the baseline image, `uid 1337`, volume and + log layout, healthchecks. +- **Compose pattern** — how a service's `compose.yaml` wires into the shared + proxy network. +- **Reverse proxy** — exposing a service at a subdomain (sanitized). + +## Conventions + +- Containers run as the services uid (`1337`) per our container standard. +- Logs land under `/srv/logs/...` mirroring the app's deploy path. +- No real hostnames, internal IPs, or exact topology in these public pages — + use placeholders and describe the pattern. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..56a4bee --- /dev/null +++ b/docs/index.md @@ -0,0 +1,46 @@ +# Rethink Studios Handbook + +The shared reference for how we build, deploy, and operate. Generic patterns and +conventions live here — sanitized for public consumption. Real infrastructure +specifics (hostnames, internal IPs, secrets, exact topology) stay in our private +runbooks. + +## Sections + +
+ +- :material-rocket-launch: __[Deploy](deploy/index.md)__ + + --- + + How services get from a repo to running behind the proxy — container + standards, compose patterns, and step-by-step deploy guides. + +- :material-ruler-square: __[Conventions](conventions/index.md)__ + + --- + + Coding, library, and infrastructure conventions. Naming, layout, logging, + and the rules that keep things consistent across projects. + +- :material-package-variant: __[Libraries](libraries/index.md)__ + + --- + + Usage docs for the shared `rethink-public` library suite — what each lib + does and how to wire it into a project. + +- :material-tools: __[Runbooks](runbooks/index.md)__ + + --- + + Operational how-tos for recurring tasks — sanitized for public reference. + +
+ +## Conventions for this handbook + +- One topic per page, grouped by section directory. +- Public means sanitized: use placeholders (``, ``, `/srv/...`) and + describe the pattern, not our literal infrastructure. +- Code blocks are tagged with their language and kept copy-pasteable. diff --git a/docs/libraries/index.md b/docs/libraries/index.md new file mode 100644 index 0000000..12be9a0 --- /dev/null +++ b/docs/libraries/index.md @@ -0,0 +1,23 @@ +# Libraries + +Usage docs for the shared `rethink-public` library suite. Before hand-rolling +common functionality, check the suite first and prefer an existing lib. + +!!! note "Work in progress" + A page per library will be added here. Browse the `rethink-public` org for + the live list — each repo's tagline says what it does. + +## Install pattern + +``` + @ git+https://git.rethinkstudios.io/rethink-public/.git@ +``` + +## Common capabilities covered by the suite + +Retry/backoff, logging setup, HTTP sessions, proxies, webhooks, IMAP/mail, +Mongo/KV/datastore, crypto/envelope, `discord.py` helpers, and timing/paths/ +masking utilities. + +If a capability isn't in the suite, build it in-project — and flag whether it's +generic enough to become a new shared lib. diff --git a/docs/runbooks/index.md b/docs/runbooks/index.md new file mode 100644 index 0000000..a177181 --- /dev/null +++ b/docs/runbooks/index.md @@ -0,0 +1,17 @@ +# Runbooks + +Operational how-tos for recurring tasks — sanitized for public reference. + +!!! note "Work in progress" + Individual runbooks will be added under this section and wired into the nav. + +## Sanitization reminder + +Runbooks often touch real infrastructure. Before a runbook goes public: + +- Replace real hostnames, internal IPs, and exact topology with placeholders + (``, ``, `/srv/...`). +- Strip secrets and credentials entirely — reference where they live, never the + values. +- Keep the procedure and the reasoning; drop the specifics that identify our + boxes. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..70ac21b --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,69 @@ +site_name: Rethink Studios Handbook +site_description: Deploy guides, infra and container standards, conventions, library usage, and runbooks. +site_url: https://docs.rethinkstudios.io/ +copyright: Rethink Studios + +theme: + name: material + language: en + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: indigo + toggle: + icon: material/weather-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: indigo + toggle: + icon: material/weather-sunny + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.sections + - navigation.top + - navigation.indexes + - toc.follow + - search.suggest + - search.highlight + - content.code.copy + - content.code.annotate + icon: + repo: fontawesome/brands/git-alt + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - tables + - toc: + permalink: true + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +plugins: + - search + +nav: + - Home: index.md + - Deploy: + - deploy/index.md + - Conventions: + - conventions/index.md + - Libraries: + - libraries/index.md + - Runbooks: + - runbooks/index.md