Ungeniuses Wiki

Developer documentation for Ungeniuses open-source projects — internals, architecture, and module deep-dives. Built with MkDocs Material.

Live site: https://ungeniuses.github.io/wiki/

---

Table of contents

• Prerequisites
• Local preview
• Adding a new project
• Adding a new module page
• Writing a module page
• Deployment
• Repo layout

---

Prerequisites

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

---

Local preview

mkdocs serve

Open http://localhost:8000. The server watches for file changes and hot-reloads automatically.

---

Adding a new project

1. Create the directory structure:

   docs/<project_name>/
     index.md          ← project landing page
     architecture.md   ← system design
     roadmap.md        ← future plans
     modules/
       index.md        ← auto-generated module list
   

   You can copy an existing project folder as a starting point:

   cp -r docs/reader.cpp docs/<project_name>

2. Add a nav section in mkdocs.yml:

   nav:
     - Home: index.md
     - reader.cpp:
       - ...
     - <project_name>:            # ← add this block
       - <project_name>/index.md
       - Architecture: <project_name>/architecture.md
       - Roadmap: <project_name>/roadmap.md
       - Modules:
         - <project_name>/modules/index.md

3. Add a project card to docs/index.md in the .wiki-card-grid section.

---

Adding a new module page

Use the scaffolding script — it creates the page and updates mkdocs.yml automatically:

python scripts/new_module.py <project_name> <module_name>
# With a custom human-readable title:
python scripts/new_module.py <project_name> <module_name> --title "My Module"

Examples:

python scripts/new_module.py reader.cpp spsc_ring_buffer
python scripts/new_module.py reader.cpp render_layer --title "Render Layer"
python scripts/new_module.py project_gacha gacha_engine --title "Gacha Engine"

The script:

1. Creates docs/<project>/modules/<module_name>.md from the template
2. Inserts a nav entry under <project> → Modules in mkdocs.yml
3. Adds a link to docs/<project>/modules/index.md

If the project doesn't exist in nav yet, it creates the full project section.

---

Writing a module page

The template at docs/_templates/module.md defines the five standard sections:

Section	What to write
Purpose	1–2 sentences: what this module does and why it exists
Location	File path(s) / line refs in the actual repo
How it works	The substantive explanation — use sub-headings, diagrams
Interfaces with	Links to other module pages it depends on or serves
Gotchas / History	Non-obvious decisions, past bugs, why-not-the-obvious

Module ≠ file. A module is a logical component with a single responsibility. Some modules span multiple files; some files contain only one module. Use judgment per-project — the script only needs a name, not a path.

---

Deployment

Deployment is fully automated via GitHub Actions (.github/workflows/deploy.yml).

Trigger: Every push to main builds the site and pushes to the gh-pages branch using mkdocs gh-deploy.

One-time repo setup (only needed on first deploy):

1. Go to Settings → Pages → Source
2. Set Branch: gh-pages, Folder: / (root)
3. Save

After that, every merge to main deploys automatically within ~1 minute.

Manual deploy (from your machine):

mkdocs gh-deploy --force --clean

---

Repo layout

wiki/
├── docs/
│   ├── index.md                  # Landing page (lists all projects)
│   ├── assets/
│   │   ├── extra.css             # Custom styles (deep purple/amber theme)
│   │   ├── extra.js              # Minimal JS enhancements
│   │   └── logo.png              # Wiki logo
│   ├── _templates/
│   │   └── module.md             # Module page template
│   ├── _overrides/               # MkDocs Material theme overrides (optional)
│   └── <project_name>/
│       ├── index.md              # Project landing page
│       ├── architecture.md
│       ├── roadmap.md
│       └── modules/
│           ├── index.md          # Module list
│           └── <module_name>.md  # One per logical component
├── scripts/
│   └── new_module.py             # Scaffolding script
├── .github/
│   └── workflows/
│       └── deploy.yml            # CI/CD: build + deploy to GitHub Pages
├── mkdocs.yml                    # MkDocs + Material configuration
├── requirements.txt              # Python dependencies
└── README.md                     # This file