Add hosted documentation site (MkDocs Material, pkgdown-style)#48
Merged
Conversation
Add a hosted documentation site (the Python equivalent of the R NNS pkgdown site) built with MkDocs + Material and deployed to GitHub Pages at https://ovvo-financial.github.io/NNS-python/. - mkdocs.yml: Material theme, search, light/dark toggle, and a nav that maps onto the existing Markdown docs: Home, Install, Quick start, API reference, API status, Conventions (+ plot parity policy), Parity with R NNS (+ sync contract/status), Benchmarks, Release notes (+ release process). Existing docs/*.md are reused; previously orphaned pages are folded in as sub-pages so nothing is unreachable. - docs/index.md, install.md, quick_start.md, release_notes.md: new pages derived from the README, kept consistent with current Stable, parity-focused messaging and the optional native-extension build. - .github/workflows/docs.yml: build with `mkdocs build --strict` and deploy via actions/deploy-pages on push to main (and manual dispatch). - pyproject.toml: add a `docs` dependency group (mkdocs-material, pymdown-extensions). - README.md: add a docs badge and link to the hosted site. - .gitignore: ignore the MkDocs `site/` build output. The site builds cleanly under `mkdocs build --strict`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwFx145eq6LfzZFFMvp8BD
The R NNS site (https://ovvo-financial.github.io/NNS/) is a pkgdown site built with Bootstrap 5 + the Bootswatch "Cosmo" theme. Bring the Material for MkDocs site visually in line with it: - Cosmo palette: blue #2780e3 primary driving a solid-blue top navbar with white text, matching link/accent colors, for both light and dark schemes (docs/stylesheets/cosmo.css). - Flat design: squared corners on code blocks, admonitions, tables, buttons, and search, mirroring Cosmo's flat aesthetic. - Typography: Source Sans 3 body / Source Code Pro mono, the Source Sans family Cosmo uses, with slightly bolder headings. - Top navbar layout via navigation.tabs (+ sticky), replacing the plain sidebar so top-level sections read like pkgdown's navbar. - The NNS hex sticker as the site logo and favicon (docs/assets/nns_hex_sticker.png), as on the pkgdown site. Site still builds cleanly under `mkdocs build --strict`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwFx145eq6LfzZFFMvp8BD
… blocks Using the actual R NNS pkgdown homepage as reference, tighten the visual match beyond the Cosmo palette/fonts: - Navbar uses a text brand (site name) like pkgdown's "NNS" brand, so the hex sticker is no longer a header logo. It now sits at the top of the home page body at width 150 (left-aligned), followed by the badges and the H1, mirroring the pkgdown landing page order. - Add Links / License / Citation / Developers sections to the home page, mirroring pkgdown's right-hand aside. - Footer credit set to "Developed by Fred Viole." to match pkgdown. - Badges recolored to the Cosmo blue (#2780e3); bold navbar brand weight. - Keep favicon as the hex sticker. Site still builds cleanly under `mkdocs build --strict`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwFx145eq6LfzZFFMvp8BD
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
2 participants
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.
Summary
Adds a hosted documentation site for
ovvo-nns— the Python equivalent of the R NNS pkgdown site — built with MkDocs + Material and deployed to GitHub Pages athttps://ovvo-financial.github.io/NNS-python/.The site is styled to match the R NNS site, which uses Bootstrap 5 + the Bootswatch Cosmo theme.
What's included
Site + content
mkdocs.yml— Material theme, search, light/dark toggle, top-navbar (tabs) layout. Nav maps onto the existing Markdown docs: Home, Install, Quick start, API reference, API status, Conventions (+ plot parity policy), Parity with R NNS (+ sync contract/status), Benchmarks, Release notes (+ release process). Existingdocs/*.mdare reused; previously orphaned pages are folded in as sub-pages so nothing is unreachable.docs/index.md,docs/install.md,docs/quick_start.md,docs/release_notes.md— derived from the README, consistent with the current Stable, parity-focused messaging and the optional native-extension build. Release notes link to the authoritative PyPI/GitHub Releases history rather than inventing a changelog (no tags exist in-repo).pkgdown / Cosmo styling
docs/stylesheets/cosmo.css— Cosmo blue#2780e3primary driving a solid-blue top navbar, matching link/accent colors (light + dark), flat/squared corners, Source Sans typography, bold navbar brand.docs/assets/nns_hex_sticker.png) at the top of the body at width 150, then badges, then the H1, plus Links / License / Citation / Developers blocks from pkgdown's right aside. Footer credit set to "Developed by Fred Viole."CI + packaging
.github/workflows/docs.yml— build withmkdocs build --strictand deploy viaactions/deploy-pageson push tomain(and manual dispatch).pyproject.toml—docsdependency group (mkdocs-material,pymdown-extensions).README.md— docs badge + link to the hosted site..gitignore— ignore the MkDocssite/build output.Validation
The site builds cleanly under
mkdocs build --strict(validated locally); the hex asset and CSS resolve in the built output.Follow-up needed before it goes live (owner-only)
main(the deploy workflow only runs there).Notes
🤖 Generated with Claude Code
Generated by Claude Code