Skip to main content

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 in site/ at the repository root.
  • These docs (at /R2K16/docs/) — built with Docusaurus 3, living in website/.

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 in scripts/docgen/ and scripts/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>.md with front matter:

    ---
    sidebar_position: 3
    ---
    # Title
  • The sidebar picks it up automatically; _category_.json in 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 (see architecture/index.md for examples).

  • Front matter title, description, sidebar_label, and sidebar_position are the ones in use.

What to keep in sync​

When you change…Update…
A project's build statusgetting-started/project-status.md (+ README)
A new top-level folderreference/repo-map.md + a module page
Roadmap/feature checklistreference/roadmap.md (+ README)
CI workflowsdevelopment/ci.md
Library versionsmodules/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:

  1. The Docusaurus docs are built with baseUrl: '/R2K16/docs/' (docs-only mode).
  2. The Jekyll primary webpage is built from site/ with actions/jekyll-build-pages — the same Jekyll engine GitHub Pages itself uses.
  3. 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 with actions/deploy-pages — no gh-pages branch is involved.

To enable it:

  1. 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).