From b088933087e4abda7ad75852cc32b485a6b1967b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Nov 2025 14:45:04 +0000 Subject: [PATCH] chore: Improve CI configuration and documentation infrastructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit addresses Phase 0.4 roadmap priorities: ## CI/CD Improvements - Remove `--ignore-missing-imports` from mypy in CI for stricter type checking - Add GitHub Actions workflow for automatic documentation deployment - Documentation now auto-deploys to GitHub Pages on docs changes ## Documentation Infrastructure - Add custom CSS styling (docs/stylesheets/extra.css) for enhanced readability - Custom color scheme for GenesisGraph brand - Priority and disclosure level badges - Improved tables, code blocks, and search results - Add custom JavaScript (docs/javascripts/extra.js) for improved UX - Version badge in header - Scroll-to-top button - Enhanced search highlighting - Keyboard shortcuts (Ctrl+K for search) - Edit on GitHub link ## Contributing Guide Enhancements - Add "Current Priorities" section linking to v0.3.0 → v1.0 roadmap - Document Phase 0.4 focus areas (test coverage, API docs, type checking) - Add guidance on high-value contributions - Include issue labels for contributor discovery ## Impact - Stricter type checking catches more errors before merge - Documentation site ready for deployment - Contributors have clear guidance on priorities - Better documentation UX for users Related to roadmap items: - Phase 0.4: Foundation & Quality (4-6 weeks) - Increase test coverage to 90%+ - Create API documentation site - Tighten type checking --- .github/workflows/ci.yml | 2 +- .github/workflows/docs.yml | 54 ++++++++ docs/developer-guide/contributing.md | 73 +++++++++++ docs/javascripts/extra.js | 127 +++++++++++++++++++ docs/stylesheets/extra.css | 178 +++++++++++++++++++++++++++ 5 files changed, 433 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/javascripts/extra.js create mode 100644 docs/stylesheets/extra.css diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2974f98..ad7a55d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,7 +33,7 @@ jobs: - name: Type check with mypy run: | - mypy genesisgraph/ --ignore-missing-imports + mypy genesisgraph/ - name: Run tests run: | diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..edb1849 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,54 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: write + +jobs: + deploy: + name: Deploy Documentation to GitHub Pages + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch all history for git-revision-date-localized plugin + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-git-revision-date-localized-plugin + + - name: Build documentation + run: | + mkdocs build --strict + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site + commit_message: 'docs: Deploy documentation [skip ci]' + user_name: 'github-actions[bot]' + user_email: 'github-actions[bot]@users.noreply.github.com' + + - name: Upload documentation artifacts + uses: actions/upload-artifact@v3 + with: + name: documentation + path: site/ diff --git a/docs/developer-guide/contributing.md b/docs/developer-guide/contributing.md index 41d919a..56ef4fe 100644 --- a/docs/developer-guide/contributing.md +++ b/docs/developer-guide/contributing.md @@ -280,12 +280,85 @@ Releases are handled by maintainers. The process includes: 3. Create GitHub release 4. Publish to PyPI +## Current Priorities (v0.3.0 → v1.0) + +GenesisGraph is on a path to v1.0 production readiness. Here are the **immediate priorities** where contributions are most valuable: + +### Phase 0.4: Foundation & Quality (Current) ⭐ **Help Wanted** + +**Timeline:** 4-6 weeks | **Status:** In Progress + +High-impact areas for new contributors: + +#### 1. Test Coverage to 90%+ 🔴 **Critical** +- **Current:** 76% overall coverage +- **Target:** ≥90% across all modules +- **Focus areas:** + - Edge cases (unicode, large files, circular dependencies) + - Integration tests for end-to-end workflows + - Performance regression tests +- **Skills needed:** Python, pytest +- **Good first issue:** Pick an untested function and write comprehensive tests + +#### 2. API Documentation 🟡 **High Priority** +- **Goal:** Auto-generated API docs with mkdocstrings +- **Tasks:** + - Enhance docstrings with examples + - Add missing type hints + - Create usage examples for each major module +- **Skills needed:** Documentation writing, Python +- **Good first issue:** Add examples to existing docstrings + +#### 3. Type Checking Improvements 🟡 **High Priority** +- **Goal:** 100% type coverage for public API +- **Current:** Mypy configured but not all modules fully typed +- **Tasks:** + - Add missing type hints + - Fix type inconsistencies + - Enable strict mypy mode +- **Skills needed:** Python, type systems + +### Upcoming Phases (Help shape the future!) + +#### Phase 0.5: Security & Lifecycle (Next) +- Formal threat model documentation +- Lifecycle & revocation framework +- Security audit preparation + +#### Phase 0.6: Delegation & Authorization (Strategic) +- AI agent authorization chains +- Policy engine integration (OPA, Cedar) +- Delegation provenance + +**See [ROADMAP.md](../strategic/roadmap.md) for complete development plan.** + +### High-Value Contributions + +These contributions have outsized impact: + +1. **Security Analysis** - Review code for vulnerabilities +2. **Performance Optimization** - Profile and optimize hot paths +3. **Real-World Examples** - Your domain's provenance use case +4. **Domain Profiles** - Industry-specific validators +5. **SDK Improvements** - Python/JavaScript SDK enhancements + +### Labels for Issues + +When looking for issues to work on: +- `good first issue` - Great for new contributors +- `help wanted` - Maintainers need community help +- `high priority` - Blocks v1.0 release +- `documentation` - Documentation improvements +- `testing` - Test coverage improvements +- `roadmap: phase-0.4` - Current phase work + ## Questions? If you have questions not covered here: - Open a GitHub Discussion - Reach out to maintainers - Check the FAQ.md +- Review [ROADMAP.md](../strategic/roadmap.md) for strategic direction --- diff --git a/docs/javascripts/extra.js b/docs/javascripts/extra.js new file mode 100644 index 0000000..0f0bddb --- /dev/null +++ b/docs/javascripts/extra.js @@ -0,0 +1,127 @@ +// GenesisGraph Documentation - Extra JavaScript + +document.addEventListener('DOMContentLoaded', function() { + // Add copy button functionality enhancements + const codeBlocks = document.querySelectorAll('pre code'); + + codeBlocks.forEach(function(codeBlock) { + // Add language label if detected + const language = codeBlock.className.match(/language-(\w+)/); + if (language && language[1]) { + const label = document.createElement('div'); + label.className = 'code-label'; + label.textContent = language[1].toUpperCase(); + label.style.cssText = 'position: absolute; top: 0; right: 45px; padding: 4px 8px; font-size: 0.7em; background: rgba(0,0,0,0.2); border-radius: 0 0 4px 4px; color: #fff;'; + codeBlock.parentElement.style.position = 'relative'; + codeBlock.parentElement.insertBefore(label, codeBlock); + } + }); + + // Add anchor link highlighting on scroll + const observer = new IntersectionObserver(entries => { + entries.forEach(entry => { + if (entry.intersectionRatio > 0) { + const id = entry.target.getAttribute('id'); + const tocLink = document.querySelector(`.md-nav__link[href="#${id}"]`); + if (tocLink) { + // Remove all active states + document.querySelectorAll('.md-nav__link--active').forEach(link => { + link.classList.remove('md-nav__link--active'); + }); + // Add active state to current + tocLink.classList.add('md-nav__link--active'); + } + } + }); + }, { + rootMargin: '-20% 0px -35% 0px' + }); + + // Observe all headings + document.querySelectorAll('h2[id], h3[id], h4[id]').forEach(heading => { + observer.observe(heading); + }); + + // Add version indicator + const version = '0.3.0'; + const header = document.querySelector('.md-header__title'); + if (header) { + const versionBadge = document.createElement('span'); + versionBadge.textContent = `v${version}`; + versionBadge.style.cssText = 'font-size: 0.7em; margin-left: 8px; padding: 2px 6px; background: rgba(255,255,255,0.2); border-radius: 3px;'; + header.appendChild(versionBadge); + } + + // Enhanced search functionality + const searchInput = document.querySelector('.md-search__input'); + if (searchInput) { + searchInput.addEventListener('input', function(e) { + const query = e.target.value.toLowerCase(); + + // Highlight search terms in results + setTimeout(() => { + const results = document.querySelectorAll('.md-search-result__article'); + results.forEach(result => { + const text = result.textContent; + if (query && text.toLowerCase().includes(query)) { + result.style.backgroundColor = 'rgba(74, 144, 226, 0.05)'; + } else { + result.style.backgroundColor = ''; + } + }); + }, 100); + }); + } + + // Add "Edit on GitHub" link to each page + const content = document.querySelector('.md-content'); + if (content) { + const editLink = document.createElement('a'); + const currentPath = window.location.pathname.replace('/genesisgraph/', ''); + editLink.href = `https://github.com/scottsen/genesisgraph/edit/main/docs${currentPath}`; + editLink.textContent = '✏️ Edit this page'; + editLink.className = 'md-button md-button--primary'; + editLink.style.cssText = 'position: fixed; bottom: 20px; right: 20px; z-index: 100; font-size: 0.8em;'; + editLink.target = '_blank'; + document.body.appendChild(editLink); + } + + // Add keyboard shortcuts hint + document.addEventListener('keydown', function(e) { + // Ctrl/Cmd + K for search + if ((e.ctrlKey || e.metaKey) && e.key === 'k') { + e.preventDefault(); + const searchButton = document.querySelector('.md-search__icon'); + if (searchButton) { + searchButton.click(); + } + } + }); + + // Add scroll-to-top button + const scrollButton = document.createElement('button'); + scrollButton.innerHTML = '↑'; + scrollButton.className = 'scroll-to-top'; + scrollButton.style.cssText = 'position: fixed; bottom: 80px; right: 20px; width: 40px; height: 40px; border-radius: 50%; background: #4a90e2; color: white; border: none; cursor: pointer; display: none; z-index: 99; font-size: 1.5em; box-shadow: 0 2px 8px rgba(0,0,0,0.2);'; + document.body.appendChild(scrollButton); + + window.addEventListener('scroll', function() { + if (window.pageYOffset > 300) { + scrollButton.style.display = 'block'; + } else { + scrollButton.style.display = 'none'; + } + }); + + scrollButton.addEventListener('click', function() { + window.scrollTo({ + top: 0, + behavior: 'smooth' + }); + }); + + // Console message for developers + console.log('%cGenesisGraph Documentation', 'font-size: 20px; font-weight: bold; color: #4a90e2;'); + console.log('%cVersion: 0.3.0', 'font-size: 12px; color: #666;'); + console.log('%cContribute: https://github.com/scottsen/genesisgraph', 'font-size: 12px; color: #666;'); +}); diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..9b4e0d2 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,178 @@ +/* GenesisGraph Documentation - Extra Styles */ + +/* Custom color scheme for GenesisGraph brand */ +:root { + --gg-primary: #4a90e2; + --gg-accent: #7cb342; + --gg-warning: #ff9800; + --gg-error: #f44336; +} + +/* Enhanced code blocks */ +.highlight { + border-left: 3px solid var(--gg-primary); +} + +/* Custom admonition styles */ +.admonition.note { + border-left-color: var(--gg-primary); +} + +.admonition.tip { + border-left-color: var(--gg-accent); +} + +.admonition.warning { + border-left-color: var(--gg-warning); +} + +.admonition.danger { + border-left-color: var(--gg-error); +} + +/* Better table styling */ +table { + border-collapse: collapse; + width: 100%; + margin: 1em 0; +} + +table th { + background-color: var(--gg-primary); + color: white; + font-weight: 600; + padding: 12px; + text-align: left; +} + +table td { + padding: 10px 12px; + border-bottom: 1px solid rgba(0, 0, 0, 0.1); +} + +table tr:hover { + background-color: rgba(74, 144, 226, 0.05); +} + +/* Code block enhancements */ +.md-typeset code { + background-color: rgba(74, 144, 226, 0.1); + padding: 2px 6px; + border-radius: 3px; +} + +.md-typeset pre code { + background-color: transparent; + padding: 0; +} + +/* Navigation breadcrumbs */ +.md-nav__link--active { + font-weight: 600; + color: var(--gg-primary); +} + +/* Custom heading anchors */ +.headerlink { + color: var(--gg-accent); + opacity: 0; + transition: opacity 0.2s; +} + +h1:hover .headerlink, +h2:hover .headerlink, +h3:hover .headerlink, +h4:hover .headerlink { + opacity: 1; +} + +/* Enhanced search results */ +.md-search-result__article { + padding: 1em; + border-left: 3px solid transparent; + transition: all 0.2s; +} + +.md-search-result__article:hover { + border-left-color: var(--gg-primary); + background-color: rgba(74, 144, 226, 0.05); +} + +/* Disclosure level badges */ +.disclosure-level-a { + background-color: #4caf50; + color: white; + padding: 2px 8px; + border-radius: 3px; + font-weight: 600; + font-size: 0.85em; +} + +.disclosure-level-b { + background-color: #ff9800; + color: white; + padding: 2px 8px; + border-radius: 3px; + font-weight: 600; + font-size: 0.85em; +} + +.disclosure-level-c { + background-color: #f44336; + color: white; + padding: 2px 8px; + border-radius: 3px; + font-weight: 600; + font-size: 0.85em; +} + +/* Priority badges from roadmap */ +.priority-critical { + background-color: #d32f2f; + color: white; + padding: 2px 8px; + border-radius: 3px; + font-weight: 600; + font-size: 0.85em; +} + +.priority-high { + background-color: #ff9800; + color: white; + padding: 2px 8px; + border-radius: 3px; + font-weight: 600; + font-size: 0.85em; +} + +.priority-medium { + background-color: #4caf50; + color: white; + padding: 2px 8px; + border-radius: 3px; + font-weight: 600; + font-size: 0.85em; +} + +/* Mermaid diagram improvements */ +.mermaid { + text-align: center; + background-color: transparent; +} + +/* Footer customization */ +.md-footer-meta { + background-color: var(--gg-primary); +} + +/* Responsive adjustments */ +@media screen and (max-width: 768px) { + table { + font-size: 0.9em; + } + + table th, + table td { + padding: 8px; + } +}