Conversation
…-roles docs: overhaul modules docs navigation and UX
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (138)
📝 WalkthroughSummary by CodeRabbitRelease Notes
WalkthroughThis PR restructures the Jekyll documentation site's navigation and UX by introducing data-driven sidebar navigation, client-side search using Lunr.js, light/dark theming with persistence, expertise-level filtering, and breadcrumb navigation. It enriches documentation front matter across 100+ pages with metadata fields ( Changes
Sequence Diagram(s)sequenceDiagram
participant Browser
participant theme.js
participant localStorage
participant CSS
participant User
participant Mermaid
Browser->>theme.js: Page load, execute before body render
theme.js->>localStorage: Read 'specfact-theme'
alt Theme found
theme.js->>CSS: Set data-theme from storage
else Theme not found
theme.js->>Browser: Check prefers-color-scheme
theme.js->>CSS: Set data-theme from system preference
end
theme.js->>Browser: Apply to document.documentElement
Browser->>CSS: Apply [data-theme] variable overrides
CSS->>Browser: Paint with correct colors
Browser->>Mermaid: Initialize with current theme
Mermaid->>Browser: Render diagrams with theme variables
User->>Browser: Click theme-toggle button
Browser->>theme.js: toggleTheme() function
theme.js->>localStorage: Persist new theme value
theme.js->>CSS: Flip data-theme attribute
CSS->>Browser: Re-paint with new theme colors
theme.js->>Mermaid: Call rerenderMermaid(newTheme)
Mermaid->>Browser: Remove SVGs, re-render with new theme
sequenceDiagram
participant User
participant Browser/DOM
participant search.js
participant search-index.json
participant Lunr.js
participant Results Display
User->>Browser/DOM: Focus search input
Browser/DOM->>search.js: On focus event
alt Index not cached
search.js->>search-index.json: Fetch lazy-load request
search-index.json-->>search.js: Return JSON page array
search.js->>Lunr.js: Build index with title/keywords boosted
Lunr.js-->>search.js: Return initialized index
end
User->>search.js: Type query (≥2 chars)
search.js->>Lunr.js: Execute search with debounce (150ms)
Lunr.js->>Lunr.js: Match against indexed fields
Lunr.js-->>search.js: Return results array
search.js->>Results Display: Render ≤10 results with title/snippet/tags
Results Display-->>Browser/DOM: Update results dropdown
User->>Browser/DOM: ArrowDown to highlight result
Browser/DOM->>Results Display: Toggle .highlighted class
User->>Browser/DOM: Press Enter on highlighted result
Browser/DOM->>Browser: Navigate to result URL
User->>Browser/DOM: Press Escape
search.js->>Results Display: Clear/hide results
search.js->>Browser/DOM: Blur input
sequenceDiagram
participant User
participant Browser/DOM
participant filters.js
participant localStorage
participant Navigation
participant Count Indicator
Browser/DOM->>filters.js: Page load, initialize expertise filter
filters.js->>localStorage: Read 'specfact-expertise'
alt Stored value exists
filters.js->>filters.js: Use stored level
else Not found
filters.js->>filters.js: Default to 'all'
end
filters.js->>Browser/DOM: Apply initial filter
User->>Browser/DOM: Click expertise pill (e.g., 'Intermediate')
Browser/DOM->>filters.js: applyFilter(level) called
filters.js->>Navigation: Iterate .docs-nav li[data-expertise]
Navigation->>Navigation: Match data-expertise against level
Navigation->>Navigation: Show/hide items (add hidden-by-filter class)
filters.js->>Navigation: Hide empty .docs-nav-bundle sections
filters.js->>Count Indicator: Update count (visible of total)
filters.js->>localStorage: Persist selected level ('specfact-expertise')
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Possibly related PRs
Suggested labels
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
|
djm81
added
documentation
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.
Summary
Promote the merged
docs-13-nav-search-theme-roleswork fromdevtomain.This release updates the modules documentation portal with the new shared shell and discoverability layer: data-driven navigation, client-side search, expertise filtering, theme toggle, updated header/footer, and refreshed overview/getting-started docs. It also includes the docs command-validation follow-up that keeps navigation targets and command examples coherent.
Refs:
Scope
packages/registry/index.json,packages/*/module-package.yaml).github/workflows/*)docs/*,README.md,AGENTS.md)scripts/sign-modules.py,scripts/verify-modules-signature.py)Bundle Impact
List impacted bundles and version updates:
nold-ai/specfact-project:no changenold-ai/specfact-backlog:no changenold-ai/specfact-codebase:no changenold-ai/specfact-spec:no changenold-ai/specfact-govern:no changeValidation Evidence
Promotion is based on merged PR #125, which passed the required docs/local validation before merge.
Required local gates
hatch run formathatch run type-checkhatch run linthatch run yaml-linthatch run check-bundle-importshatch run contract-testhatch run smart-test(orhatch run test)Signature + version integrity (required)
hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bumpCI and Branch Protection
verify-module-signaturesquality (3.11)quality (3.12)quality (3.13)Docs / Pages
docs/)docs-pages.yml, if changed)specfact-clidocs updated (if applicable)Checklist