Rosetta Stone DB (prototype)

This repository is a prototype website and corpus for the MaRDI file format for mathematical software.

It stores:

• a human-readable description per example
• code to generate the object in a given system
• the serialized data emitted by that system

It also generates a browsable static site with:

• a front page linking to the specification and the rosetta stone
• a specification section covering the overall format and selected data types
• a rosetta-stone index grouped by category (and optional subcategory)
• per-example pages with code and serialized data for each available system
• Markdown and HTML output

Repository layout

Input data

All source example material lives under rosetta/:

rosetta/<category>/<example-slug>/description.md
rosetta/<category>/<example-slug>/systems/<SystemName>/generate.*
rosetta/<category>/<example-slug>/systems/<SystemName>/data.*

Example:

rosetta/polyhedral/complete-graph/description.md
rosetta/polyhedral/complete-graph/systems/Oscar.jl/generate.jl
rosetta/polyhedral/complete-graph/systems/Oscar.jl/data.mrdi

Site generator

• Script: webpage/generate_page.py
• Input: rosetta/
• Output directory: _site/ (generated files, ignored by git)

Generated output includes:

• _site/index.md
• _site/index.html
• _site/spec/index.md and _site/spec/index.html
• _site/rosetta/index.md and _site/rosetta/index.html
• one .md and one .html page per example under _site/rosetta/, e.g. _site/rosetta/groups/free-group.md and _site/rosetta/groups/free-group.html

Metadata in description.md

Each example description starts with YAML frontmatter:

---
title: Complete graph
category: polyhedral
subcategory: combinatorics
---

Required:

• title
• category

Optional:

• subcategory (used for sub-grouping and sorting in the index)

category and subcategory are internal keys (slug-like). Display names and ordering are configured in webpage/config.json.

Local development

Install dependencies:

pip install -r requirements.txt

Install development tooling:

pip install -r requirements-dev.txt

Generate the site:

python3 webpage/generate_page.py

Run type checking:

mypy webpage

Notes:

• Markdown is converted to HTML using marko (with GFM extension).
• Math rendering uses MathJax in generated HTML.
• Code blocks use highlight.js and include a copy button.
• JSON data.* is rendered with compact pretty-printing on pages.
• mypy is configured in pyproject.toml.

GitHub Pages

The repository contains a workflow at .github/workflows/publish-pages.yml that:

• installs Python dependencies
• runs python3 webpage/generate_page.py
• publishes _site/ via GitHub Pages

Dependabot config for GitHub Actions updates is in:

• .github/dependabot.yml

Guidelines for good examples

Prefer distinctive values

Use values that are easy to identify in serialized output. Tiny or repetitive values are harder to match across systems.

Avoid overly symmetric objects

Prefer examples that make structure visible in serialized form (for example, nontrivial matrices instead of highly symmetric zero matrices).