Replace project page with the full docs.md specification - #4
Merged
Merged
Conversation
Requested: the GitHub Pages site (docs/index.html) now renders docs.md in full, instead of the shorter curated landing page (the "3 findings" summary from PR #2), so a reader following the project-page link gets the complete vision document / scientific specification / roadmap, not a digest. Converted programmatically (docs.md is the single source of truth -- this page is generated from it, not hand-copied) with Python-Markdown (extra + toc + sane_lists extensions): all 30 sections, ASCII architecture diagrams, tables, and blockquotes preserved verbatim. LaTeX math ($...$/$$...$$) is protected from Markdown's underscore-based emphasis parser before conversion (subscripts like X_{model} would otherwise be mangled) and rendered client-side via MathJax. Layout: sticky table-of-contents sidebar on desktop (the spec has 30 top-level sections plus subsections, too long to scroll blind), a collapsible <details> TOC on narrow screens, reusing the existing site's CSS design tokens/typography. docs.md's own §0 methodological disclaimer (all figures are experimental targets, not results) stays intact and is the first section on the page, so nothing here reframes the doc as a results report. The prior page's own "3 findings" content (47% top-1, the rho correction, the Xavier/He bug) isn't lost -- it lives in the README and this project's `results/reports/*.md`, linked from the page's header ("Verified results (README)"). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WSc9sb1otU6ssfxDBzeNHG
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Team Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Content is unchanged (still the full docs.md); this is a design pass requested ahead of sharing the link widely, so it reads as a finished project page rather than a raw markdown dump: - Section numbers pulled out of h2/h3 text into accent-colored chips (the same design language the original curated landing page used), instead of plain "3. Scientific Problem" text. - Proper type scale (Inter for body copy, JetBrains Mono for labels/ code -- both Google Fonts), tighter line length on the content column, clearer spacing rhythm between sections. - Hero rewritten: subtle background treatment, primary/secondary link buttons (repo / verified results / raw source), and an explicit methodological-note callout up front so the spec-vs-results distinction is visible before a reader scrolls past it in §0. - Sticky TOC now highlights the section currently in view (IntersectionObserver, no dependency). - Wide tables wrap in a horizontally-scrollable container instead of overflowing the fixed-width column on narrow screens. - Open Graph / Twitter Card meta tags, so a shared link renders a proper title and description instead of nothing. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WSc9sb1otU6ssfxDBzeNHG
7 tasks
rustnew
added a commit
that referenced
this pull request
Sep 3, 2026
Requested ahead of the wider Reddit launch: the ASCII-art pipeline/tree diagrams throughout docs.md (§8, §9.5, §9.9-9.10, §9.15, §12-14, §17, §19.1, §25 x3, §29 -- 14 diagrams total) render as literal monospace text and don't scale to a public page. Replaced with equivalent Mermaid flowcharts (a quadrant chart for §9.9's Pareto front), colored via per-diagram `classDef` (soft red for reject/stop states, green for confirm/ground-truth states, blue for terminal "next generation" states) so every diagram is self-contained and renders correctly and consistently both on the built page and natively on GitHub when viewing docs.md directly -- no page-specific styling required to read it correctly. Content is unchanged: every diagram carries the exact same nodes and flow as its ASCII original, just structured and colored instead of hand-drawn with box-drawing characters. Plain example-output and list blocks that aren't actually diagrams (the learning-rate output example, the failure-category list, the TRAIN/VAL/TEST description, the baseline comparison list) are intentionally left as plain code blocks -- forcing those into Mermaid would add structure that isn't there. docs/index.html regenerated from docs.md via the existing build script, extended to convert Python-Markdown's `<pre><code class="language- mermaid">` fenced-code output into the `<pre class="mermaid">` shape mermaid.js expects, plus a page-level mermaid.initialize() call (theme matched to the site's existing palette) loaded from jsdelivr. Rebased onto main after PR #4 (docs/full-spec-page) merged before this change was pushed -- this is the same diff, targeted at current main. Claude-Session: https://claude.ai/code/session_01WSc9sb1otU6ssfxDBzeNHG Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
rustnew
added a commit
that referenced
this pull request
Sep 4, 2026
* Replace ASCII architecture diagrams with colored Mermaid diagrams Requested ahead of the wider Reddit launch: the ASCII-art pipeline/tree diagrams throughout docs.md (§8, §9.5, §9.9-9.10, §9.15, §12-14, §17, §19.1, §25 x3, §29 -- 14 diagrams total) render as literal monospace text and don't scale to a public page. Replaced with equivalent Mermaid flowcharts (a quadrant chart for §9.9's Pareto front), colored via per-diagram `classDef` (soft red for reject/stop states, green for confirm/ground-truth states, blue for terminal "next generation" states) so every diagram is self-contained and renders correctly and consistently both on the built page and natively on GitHub when viewing docs.md directly -- no page-specific styling required to read it correctly. Content is unchanged: every diagram carries the exact same nodes and flow as its ASCII original, just structured and colored instead of hand-drawn with box-drawing characters. Plain example-output and list blocks that aren't actually diagrams (the learning-rate output example, the failure-category list, the TRAIN/VAL/TEST description, the baseline comparison list) are intentionally left as plain code blocks -- forcing those into Mermaid would add structure that isn't there. docs/index.html regenerated from docs.md via the existing build script, extended to convert Python-Markdown's `<pre><code class="language- mermaid">` fenced-code output into the `<pre class="mermaid">` shape mermaid.js expects, plus a page-level mermaid.initialize() call (theme matched to the site's existing palette) loaded from jsdelivr. Rebased onto main after PR #4 (docs/full-spec-page) merged before this change was pushed -- this is the same diff, targeted at current main. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WSc9sb1otU6ssfxDBzeNHG * Add favicon and status badges to the spec page QA pass on the merged page (structural review: HTML validity, TOC-to- heading anchor consistency across all 63 sections, external resource availability -- all checked out clean) surfaced two real gaps versus the original curated landing page this replaced: - No favicon at all (generic/blank browser tab icon) -- added a small inline SVG data URI (no extra asset file), a rounded square with the site's own accent blue and a "P" mark. - The CI/license/Python-version badges from the original page's hero were dropped when the whole page became docs.md's content -- restored them, since they're a real trust signal for a page about to be shared publicly (build passing, license, supported Python version at a glance). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WSc9sb1otU6ssfxDBzeNHG --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed and why
Replaces the curated "3 findings" landing page at
docs/index.html(GitHub Pages) with the full
docs.mdspecification, per request:a reader following the project-page link now gets the complete vision
document / scientific spec / roadmap (30 sections) instead of a digest.
Evidence
Not a results/code change -- presentation only, and generated, not
$...$ / $$...$$ )
hand-copied: a small conversion pass (Python-Markdown,
extra+toc+sane_lists) turnsdocs.mdinto this page, so the page can't driftfrom the source doc. All 30 sections, every ASCII architecture diagram,
table, and blockquote carried over verbatim; LaTeX math (
is protected from Markdown's underscore emphasis parser before
conversion (subscripts like
X_{model}would otherwise be mangled by_..._) and rendered client-side via MathJax.of a script run.
docs.md: it isdocs.md.docs.md's own §0 disclaimer ("experimental targets, not results
already obtained") is the first section on the page, unchanged.
Layout: a sticky table-of-contents sidebar on desktop (30 top-level
sections is too long to scroll blind), collapsing into a
<details>toggle on narrow screens, reusing the existing site's CSS tokens.
Checklist
reproduce.yml) passes on this branch (docs-only change,unaffected).
data/meta_dataset.dbnot touched.referenced there -- N/A, docs.md itself is unchanged, only its
HTML rendering is new.
Open questions / requested feedback
The prior page's "3 findings" summary (47% top-1 accuracy, the rho
0.670→0.395 correction, the Xavier/He bug) is no longer on the landing
page itself -- it still lives in the README and
results/reports/*.md,and the page's header links to the README as "Verified results". Flagging
in case a link back to that summary from within the spec page itself
(rather than just the header) is wanted on a follow-up.