rinx

rinx is a Rust re-implementation of (a subset of) the Sphinx documentation generator, built to be a first-class Bazel build step rather than an external tool wrapped by one. It turns reStructuredText into an HTML site with cross-references, toctree navigation, syntax highlighting, math and diagrams, and it models requirements and other project-specific constructs the way sphinx-needs does.

This site is itself built by rinx, from the docs/ directory of its repository.

Why

A Sphinx build is a single process: it re-reads the whole project and decides for itself what is out of date. rinx splits the work into small, deterministic steps (parse, index, render), each of them a separate Bazel action. So:

• Only what changed is rebuilt. Editing one page re-parses that page only. Results are cached like any other Bazel output, including remote caches.

• Documentation composes like code. A rinx_library per team or component, a rinx_site that assembles them, and dependency checking that fails the build when a toctree points at a library that isn't declared.

• Fast. CPython's documentation (about 500 documents) builds as a Bazel target; see Benchmarking Rinx.

• Resilient parsing. A half-written document still produces a page, which is what makes the VS Code live preview possible.

Contents

• Getting started
  • Adding rinx to a project
  • A first site
  • Building and viewing it
  • Where to go next
• Bazel rules
  • rinx_library
  • rinx_site
  • rinx_inventory
  • rinx_doctest_tests
• Supported syntax
  • reStructuredText
  • Sphinx
  • Extensions
  • Diagnostics
• Entities
  • The four kinds of declaration
  • Declaring a type
  • Identity
  • Cardinality
  • Sections
  • Relations and back-links
  • Roles
  • Presentation
  • Build wiring
  • Editor support for the schema file
  • Listing entities
  • Flowcharts of the graph
  • Sequence diagrams of the graph
  • Charting the graph
  • Diagramming entities
  • Migrating from sphinx-needs
  • Importing from sphinx-needs
  • Diagnostics
• Linking between documentation sites
  • Linking into another site
  • Writing references
  • Letting other sites link into yours
  • What the inventory lists
  • Live preview
• VS Code Extension Architecture for Rinx
  • Core Philosophy
  • Architecture Overview
  • Caveats & Required Changes
  • Benefits
  • Future Enhancements
  • Development and Local Testing
• Benchmarking Rinx
  • Benchmarking Rinx
  • The CPython benchmark
  • Benchmarking the entity model

More

• The example site is a multi-team project using every feature rinx supports, built from examples/ in the repository.

• The architecture decision records explain why rinx is built the way it is.

• The source, issues and discussions are on GitHub.