Maintaining the docs site
The published site at https://havaianasdestruido.github.io/R2K16/ has two parts:
- The primary webpage (at
/R2K16/) — a Jekyll site living insite/at the repository root. - These docs (at
/R2K16/docs/) — built with Docusaurus 3, living inwebsite/.
The documentation combines human-written architectural guides with comprehensive, automatically generated codebase documentation:
- Human-written documentation (under
website/docs/for architecture, modules, development, reference). - Automated Codebase Reference (under
website/docs/codebase/) — generated and maintained via Python scripts inscripts/docgen/andscripts/generate_docs.py. It automatically detects all functions across the codebase, analyzes internal logic, maps test usages, and identifies cross-platform behavioral differences.
Running locally
cd website
npm install # first time only
npm run generate-docs # generates codebase documentation via Python
npm start # dev server on http://localhost:3000 with hot reload
npm start binds 0.0.0.0:3000 (already configured in package.json).
Production build & preview
npm run build # runs prebuild (Python docgen) + Docusaurus build
npm run serve # serves the production build
Automated Codebase Documentation Generator
The documentation generator (scripts/generate_docs.py) automatically maintains the website/docs/codebase/ documentation tree. It is designed to automatically detect and document newly added functions, test cases, and platform variants as the engine evolves.
Architecture of the Python Generator
scripts/
├── generate_docs.py # CLI entrypoint for documentation generation
└── docgen/
├── __init__.py # Module exports
├── config.py # Subsystem mappings, module list, exclusions
├── models.py # Data models for functions, tests, analysis
├── parser.py # C++, C#, Python AST and regex function extractor
├── analyzer.py # Internal logic, memory, concurrency & assert analyzer
├── test_mapper.py # Boost/MSUnit test suite parser & assertion mapper
├── divergence_detector.py # Preprocessor guards (#ifdef) & multi-file divergence
└── markdown_generator.py # Production-grade Docusaurus Markdown & MDX generator
CLI Options
# Generate all codebase documentation into website/docs/codebase/
python3 scripts/generate_docs.py
# Check statistics without modifying files
python3 scripts/generate_docs.py --stats-only
# Dry-run validation check
python3 scripts/generate_docs.py --check
# Custom output directory
python3 scripts/generate_docs.py --output-dir /path/to/docs
The base-URL gotcha
The docs default to baseUrl: '/R2K16/docs/' because on GitHub Pages they are served
under /R2K16/docs/ — the primary webpage (Jekyll, site/) owns /R2K16/ itself. The
Docusaurus app runs in docs-only mode (routeBasePath: '/', no landing page), and
intro.md carries slug: / so the docs root /R2K16/docs/ serves the introduction.
When hosting the build at the root of a host (or in a sandbox preview), override it:
DOCUSAURUS_BASE_URL=/docs/ npm run build && DOCUSAURUS_BASE_URL=/docs/ npm run serve
The dev server (npm start) does not care about the base URL.
Site layout
site/ # Jekyll — the primary webpage at /R2K16/
├── _config.yml # baseurl /R2K16, title, description
├── _layouts/ # default.html (header/footer) + home.html (hero)
├── assets/ # stylesheet, logo & favicon
├── index.md # the landing page content
└── 404.html # custom "page not found" page
website/
├── docusaurus.config.js # Site metadata, navbar, footer, theming, mermaid
├── sidebars.js # Autogenerated sidebars from docs/ structure
├── docs/ # ← the documentation (Markdown + front matter)
│ ├── intro.md # slug: / → served at /R2K16/docs/
│ ├── getting-started/ # _category_.json sets label/order
│ ├── architecture/ # engine internals (+ mermaid diagrams)
│ ├── modules/ # per-project reference
│ ├── development/ # CI, security, conventions, this page
│ └── reference/ # repo map, glossary, roadmap, troubleshooting, FAQ
└── static/img/ # Logo & favicon
Writing docs
-
Create
docs/<category>/<slug>.mdwith front matter:---sidebar_position: 3---# Title -
The sidebar picks it up automatically;
_category_.jsonin each folder controls the category's label and position. -
Relative links between docs (
. /other-page.md) get validated at build time —onBrokenLinks: 'throw'means broken links fail the build. -
Code blocks get syntax highlighting for C++, Lua, CMake, bash and more via Prism (configured in
docusaurus.config.js). -
Mermaid diagrams are enabled — fence a block with
mermaid(seearchitecture/index.mdfor examples). -
Front matter
title,description,sidebar_label, andsidebar_positionare the ones in use.
What to keep in sync
| When you change… | Update… |
|---|---|
| A project's build status | getting-started/project-status.md (+ README) |
| A new top-level folder | reference/repo-map.md + a module page |
| Roadmap/feature checklist | reference/roadmap.md (+ README) |
| CI workflows | development/ci.md |
| Library versions | modules/libraries.md (+ README) |
Deployment (GitHub Pages)
The workflow .github/workflows/docs-deploy.yml (in the repository root) builds both
parts of the site and publishes them together to GitHub Pages on every push to main
that touches site/**, website/** or the workflow itself:
- The Docusaurus docs are built with
baseUrl: '/R2K16/docs/'(docs-only mode). - The Jekyll primary webpage is built from
site/withactions/jekyll-build-pages— the same Jekyll engine GitHub Pages itself uses. - The Docusaurus build is copied under
docs/of the Jekyll build, and the combined directory is uploaded as the Pages artifact (actions/upload-pages-artifact) and deployed withactions/deploy-pages— nogh-pagesbranch is involved.
To enable it:
- Repository Settings → Pages → Source: GitHub Actions — the workflow uploads the build artifact and deploys it directly.
Published URLs:
- Primary webpage:
https://<user>.github.io/R2K16/ - Docs:
https://<user>.github.io/R2K16/docs/
For other hosts (Netlify, Vercel, plain nginx), build with the right base URL:
DOCUSAURUS_BASE_URL=/docs/ npm run build
and upload website/build/.
Upgrading Docusaurus
cd website
npm outdated @docusaurus/core @docusaurus/preset-classic @docusaurus/theme-mermaid
npm install @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/theme-mermaid@latest
npm run build # verify
Node ≥ 18 is required (package.json engines field).