Skip to content

docs: wire check:examples into CI, derive the status badge, consolidate the IA #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sean-Koval merged 3 commits into from
Aug 31, 2026
Merged

docs: wire check:examples into CI, derive the status badge, consolidate the IA #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
756ef30
ci: run check:examples in the docs-checks job
Sean-Koval Aug 31, 2026
47e1035
docs: derive the status badge from frontmatter via a Banner override
Sean-Koval Aug 31, 2026
5e42e30
docs: consolidate the IA — one module index, seven sidebar groups
Sean-Koval Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,17 @@ jobs:

docs-checks:
runs-on: ubuntu-latest
env:
CARGO_TERM_COLOR: always
PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
with:
bun-version: latest
# check:examples cargo-checks every documented Rust example against the
# real crate, so this job needs a toolchain as well as bun.
- uses: dtolnay/rust-toolchain@stable
- name: Install docs dependencies
run: bun install --frozen-lockfile
working-directory: docs-site
Expand All @@ -44,3 +50,6 @@ jobs:
- name: Check content schema
run: bun run check:content-schema
working-directory: docs-site
- name: Check documented Rust examples compile
run: bun run check:examples
working-directory: docs-site
257 changes: 132 additions & 125 deletions docs-site/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,19 @@ export default defineConfig({
'katex/dist/katex.min.css',
'./src/styles/starlight.css',
],
components: {
// Derives each page's status pill from its `status` frontmatter rather
// than from hand-written markup in `banner.content`.
Banner: './src/components/DocStatusBanner.astro',
},
social: [
{ icon: 'github', label: 'GitHub', href: 'https://github.com/Open-Quant/openquant' },
],
// Seven top-level groups. It was twenty, thirteen of them one AFML
// chapter each and five holding a single page, so a reader scrolled past
// a chapter menu to reach Reference, Governance and Coverage. The AFML
// chapters are still here — nested one level inside Modules, where a
// one-page chapter costs a line rather than a heading.
sidebar: [
{
label: 'Getting Started',
Expand All @@ -64,144 +74,138 @@ export default defineConfig({
autogenerate: { directory: 'setup' },
},
{
label: 'Core Workflows',
label: 'Workflows',
autogenerate: { directory: 'workflows' },
},
// ── AFML Chapter-based module groups ──
{
label: 'Ch 2: Data Structures',
items: [
{ slug: 'modules/data-structures' },
{ slug: 'modules/filters' },
{ slug: 'modules/etf-trick' },
],
},
{
label: 'Ch 3: Labeling',
items: [
{ slug: 'modules/labeling' },
{ slug: 'modules/bet-sizing' },
],
},
{
label: 'Ch 4: Sample Weights',
items: [
{ slug: 'modules/sampling' },
{ slug: 'modules/sample-weights' },
{ slug: 'modules/sb-bagging' },
],
},
{
label: 'Ch 5: Fractional Differentiation',
label: 'Modules',
items: [
{ slug: 'modules/fracdiff' },
],
},
{
label: 'Ch 6: Ensemble Methods',
items: [
{ slug: 'modules/ensemble-methods' },
],
},
{
label: 'Ch 7: Cross-Validation',
items: [
{ slug: 'modules/cross-validation' },
],
},
{
label: 'Ch 8: Feature Importance',
items: [
{ slug: 'modules/feature-importance' },
{ slug: 'modules/fingerprint' },
],
},
{
label: 'Ch 9: Hyperparameter Tuning',
items: [
{ slug: 'modules/hyperparameter-tuning' },
],
},
{
label: 'Ch 10–12: Backtesting',
items: [
{ slug: 'modules/backtesting-engine' },
{ slug: 'modules/synthetic-backtesting' },
],
},
{
label: 'Ch 14–15: Diagnostics & Risk',
items: [
{ slug: 'modules/backtest-statistics' },
{ slug: 'modules/risk-metrics' },
{ slug: 'modules/strategy-risk' },
],
},
{
label: 'Ch 16: Portfolio Construction',
items: [
{ slug: 'modules/hrp' },
{ slug: 'modules/hcaa' },
{ slug: 'modules/onc' },
{ slug: 'modules/cla' },
{ slug: 'modules/portfolio-optimization' },
],
},
{
label: 'Ch 17–19: Microstructure & Regimes',
items: [
{ slug: 'modules/structural-breaks' },
{ slug: 'modules/microstructural-features' },
{ slug: 'modules/codependence' },
],
},
{
label: 'Ch 20–22: HPC & Advanced',
items: [
{ slug: 'modules/hpc-parallel' },
{ slug: 'modules/combinatorial-optimization' },
{ slug: 'modules/streaming-hpc' },
],
},
{
label: 'Shared Utilities',
items: [
{ slug: 'modules/ef3m' },
{ slug: 'modules/util-fast-ewma' },
{ slug: 'modules/util-volatility' },
],
},
// ── Python-only modules ──
{
label: 'Python Modules',
items: [
{ slug: 'modules/data' },
{ slug: 'modules/feature-diagnostics' },
{ slug: 'modules/pipeline' },
{ slug: 'modules/research' },
{ slug: 'modules/adapters' },
{ slug: 'modules/viz' },
{ label: 'All Modules', link: '/modules/' },
{
label: 'Ch 2: Data Structures',
collapsed: true,
items: [
{ slug: 'modules/data-structures' },
{ slug: 'modules/filters' },
{ slug: 'modules/etf-trick' },
],
},
{
label: 'Ch 3: Labeling',
collapsed: true,
items: [
{ slug: 'modules/labeling' },
{ slug: 'modules/bet-sizing' },
],
},
{
label: 'Ch 4: Sample Weights',
collapsed: true,
items: [
{ slug: 'modules/sampling' },
{ slug: 'modules/sample-weights' },
{ slug: 'modules/sb-bagging' },
],
},
{
label: 'Ch 5–7: Features & Validation',
collapsed: true,
items: [
{ slug: 'modules/fracdiff' },
{ slug: 'modules/ensemble-methods' },
{ slug: 'modules/cross-validation' },
],
},
{
label: 'Ch 8–9: Importance & Tuning',
collapsed: true,
items: [
{ slug: 'modules/feature-importance' },
{ slug: 'modules/fingerprint' },
{ slug: 'modules/hyperparameter-tuning' },
],
},
{
label: 'Ch 10–12: Backtesting',
collapsed: true,
items: [
{ slug: 'modules/backtesting-engine' },
{ slug: 'modules/synthetic-backtesting' },
],
},
{
label: 'Ch 14–15: Diagnostics & Risk',
collapsed: true,
items: [
{ slug: 'modules/backtest-statistics' },
{ slug: 'modules/risk-metrics' },
{ slug: 'modules/strategy-risk' },
],
},
{
label: 'Ch 16: Portfolio Construction',
collapsed: true,
items: [
{ slug: 'modules/hrp' },
{ slug: 'modules/hcaa' },
{ slug: 'modules/onc' },
{ slug: 'modules/cla' },
{ slug: 'modules/portfolio-optimization' },
],
},
{
label: 'Ch 17–19: Microstructure & Regimes',
collapsed: true,
items: [
{ slug: 'modules/structural-breaks' },
{ slug: 'modules/microstructural-features' },
{ slug: 'modules/codependence' },
],
},
{
label: 'Ch 20–22: HPC & Advanced',
collapsed: true,
items: [
{ slug: 'modules/hpc-parallel' },
{ slug: 'modules/combinatorial-optimization' },
{ slug: 'modules/streaming-hpc' },
],
},
{
label: 'Shared Utilities',
collapsed: true,
items: [
{ slug: 'modules/ef3m' },
{ slug: 'modules/util-fast-ewma' },
{ slug: 'modules/util-volatility' },
],
},
{
label: 'Python Modules',
collapsed: true,
items: [
{ slug: 'modules/data' },
{ slug: 'modules/feature-diagnostics' },
{ slug: 'modules/pipeline' },
{ slug: 'modules/research' },
{ slug: 'modules/adapters' },
{ slug: 'modules/viz' },
],
},
],
},
// ── Reference ──
{
label: 'Reference',
items: [
{ slug: 'module-reference/api-surfaces' },
{ slug: 'module-reference/by-afml-chapter' },
{ slug: 'module-reference/indexing-and-discovery' },
{ label: 'All Modules', link: '/modules/' },
{ slug: 'examples/catalog' },
],
},
{
label: 'Examples',
autogenerate: { directory: 'examples' },
},
{
label: 'Governance & Release',
label: 'Governance',
autogenerate: { directory: 'governance' },
},
{ label: 'Coverage Dashboard', link: '/coverage/' },
{ label: 'Coverage', link: '/coverage/' },
],
}),
],
Expand All @@ -210,11 +214,14 @@ export default defineConfig({
'/guides': '/openquant/workflows/rust-core-workflow/',
'/tutorials': '/openquant/workflows/python-core-workflow/',
'/notebook-research-workflow': '/openquant/workflows/notebook-research-workflow/',
'/api-reference': '/openquant/module-reference/api-surfaces/',
// api-surfaces.md was merged into the module index as 'By language surface'.
'/api-reference': '/openquant/modules/',
'/examples': '/openquant/examples/catalog/',
// '/modules' intentionally absent: it shadowed the real modules/index.md page
// and broke the homepage "Browse Modules" CTA.
'/search': '/openquant/module-reference/indexing-and-discovery/',
// indexing-and-discovery.md described the sidebar; its discovery paths now
// live on the home page.
'/search': '/openquant/',
'/publishing': '/openquant/governance/versioning-and-release-policy/',
'/performance': '/openquant/governance/benchmark-policy/',
'/contributing': '/openquant/governance/support-and-escalation/',
Expand Down
Loading
Loading