solarwindpy 0.0.1.dev0__py3-none-any.whl → 0.1.0__py3-none-any.whl

plans/readthedocs-simplified/0-Overview.md

@@ -0,0 +1,243 @@
+# ReadTheDocs Simplified Integration Plan - Overview
+
+## Plan Metadata
+- **Plan Name**: ReadTheDocs Simplified Integration
+- **Created**: 2025-08-20
+- **Branch**: master
+- **Implementation Branch**: feature/readthedocs-simplified
+- **Coordinator**: UnifiedPlanCoordinator
+- **Structure**: Multi-Phase (5 phases)
+- **Total Phases**: 5
+- **Dependencies**: None
+- **Affects**: Documentation system, ReadTheDocs integration
+- **Estimated Duration**: 2 hours
+- **Status**: Planning
+
+## Phase Overview
+- [ ] **Phase 1: Immediate Doc8 Fixes** (Est: 10 minutes) - Fix linting errors blocking CI/CD
+- [ ] **Phase 2: Template Simplification** (Est: 30 minutes) - Keep basic templates, remove complexity
+- [ ] **Phase 3: ReadTheDocs Setup** (Est: 40 minutes) - Minimal configuration and manual setup
+- [ ] **Phase 4: Testing & Validation** (Est: 40 minutes) - Verify persistence and deployment
+- [ ] **Phase 5: Closeout** (Est: 20 minutes) - Document lessons learned and velocity metrics
+
+## Phase Files
+1. [1-Immediate-Fixes.md](./1-Immediate-Fixes.md)
+2. [2-Template-Simplification.md](./2-Template-Simplification.md)
+3. [3-ReadTheDocs-Setup.md](./3-ReadTheDocs-Setup.md)
+4. [4-Testing-Validation.md](./4-Testing-Validation.md)
+5. [5-Closeout.md](./5-Closeout.md)
+
+## 🎯 Objective
+Implement pragmatic ReadTheDocs documentation deployment with **minimal complexity** while preserving essential template persistence capability. Deliver working documentation in 2 hours instead of 10+.
+
+## 🧠 Critical Context: Why Templates Are Required
+
+### The Persistence Problem
+**CRITICAL ISSUE**: RST files in `docs/source/api/` are ephemeral and regenerated on every documentation build.
+
+- **52 API documentation files** are auto-generated by `sphinx-apidoc`
+- These files are **git-ignored** (line 75 in `.gitignore`: `docs/source/api/`)
+- **Complete regeneration** occurs on every `make html` or CI/CD build
+- **100% data loss** of any manual edits to these files
+
+### The ONLY Solution: Templates
+Templates in `docs/source/_templates/autosummary/` are the **only way** to persist customizations:
+- Templates survive rebuilds (they're not regenerated)
+- Single-point control for all 52 modules
+- Changes automatically propagate to all API documentation
+
+**Without templates**: No API documentation customization is possible. Period.
+
+## 🚀 What We're Building (2 hours total)
+
+### Phase 1: Immediate Fixes (10 minutes)
+- Fix doc8 linting errors blocking CI/CD
+- Missing newlines at EOF (4 files)
+- Trailing whitespace issues
+- Line length violations
+
+### Phase 2: Template Simplification (30 minutes)  
+- Keep existing basic template infrastructure
+- Remove complex physics-aware enhancements
+- Maintain essential :no-index: post-processing
+- Document template usage clearly
+
+### Phase 3: ReadTheDocs Setup (40 minutes)
+- Create minimal .readthedocs.yaml configuration
+- Manual ReadTheDocs project setup
+- Test basic HTML deployment
+- No advanced features (PDF, webhooks, etc.)
+
+### Phase 4: Testing & Validation (40 minutes)
+- Verify template persistence across rebuilds
+- Confirm ReadTheDocs builds successfully
+- Test CI/CD unblocking
+- Document success criteria
+
+## ❌ What We're NOT Building (Saves 8+ hours)
+
+### Over-Engineering We're Avoiding
+- **Physics-aware template enhancements** - Can be added later if needed
+- **Complex quality validation frameworks** - Basic Sphinx warnings sufficient
+- **Multiple output formats** (PDF/EPUB) - HTML only for now
+- **Comprehensive badge collections** - One ReadTheDocs badge sufficient
+- **Automated webhook deployment pipelines** - Manual setup works fine
+- **Custom validation scripts** - Standard tooling adequate
+
+### Why This Simplification Works
+1. **Core requirement met**: Template persistence preserved
+2. **Immediate value**: Documentation online quickly
+3. **Incremental path**: Can enhance later if needed
+4. **Standard patterns**: What most Python packages actually use
+5. **Risk reduction**: Less complex code to maintain
+
+## 📊 Value Proposition Analysis
+
+### Comparison with Over-Engineered Approach
+
+| Aspect | Simplified (This Plan) | Over-Engineered (Abandoned) | Benefit |
+|--------|----------------------|----------------------------|---------|
+| **Implementation Time** | 2 hours | 10+ hours | **80% time savings** |
+| **Complexity** | Low | High | **Easier maintenance** |
+| **Template Persistence** | ✅ Full capability | ✅ Full capability | **Same core value** |
+| **ReadTheDocs Deployment** | ✅ Working | ✅ Working | **Same end result** |
+| **Physics Documentation** | ❌ Not included | ✅ Included | **Deferrable feature** |
+| **CI/CD Unblocking** | ✅ Immediate | ✅ After 10 hours | **90% faster delivery** |
+| **Documentation Quality** | ✅ Professional | ✅ Enhanced | **Good enough initially** |
+
+### ROI Analysis
+- **Investment**: 2 hours vs 10+ hours
+- **Immediate value**: CI/CD unblocked, docs online
+- **Risk reduction**: 80% less code to maintain
+- **Flexibility**: Can enhance incrementally
+
+## ✅ Success Criteria
+
+### Technical Requirements
+- [ ] Doc8 linting passes without errors
+- [ ] Documentation builds successfully with minimal warnings
+- [ ] ReadTheDocs deployment functional (HTML output)
+- [ ] Template customizations persist across rebuilds
+- [ ] CI/CD workflows no longer blocked
+
+### Quality Standards
+- [ ] Professional HTML rendering
+- [ ] All API modules documented
+- [ ] Navigation and search working
+- [ ] Basic template infrastructure preserved
+
+### Developer Experience
+- [ ] Clear documentation of template usage
+- [ ] Simple build process (`make html` works)
+- [ ] Fast feedback loop (quick builds)
+- [ ] Minimal maintenance overhead
+
+## 🧪 Testing Strategy
+
+### Phase-by-Phase Validation
+1. **Doc8 fixes**: Verify linting passes
+2. **Template preservation**: Test customization persistence
+3. **ReadTheDocs deployment**: Confirm online documentation
+4. **CI/CD integration**: Verify workflow success
+
+### Regression Prevention
+- Document template editing process
+- Establish build quality checks
+- Simple validation procedures
+
+## 🔧 Git Workflow
+
+### Branch Strategy
+```bash
+# Create implementation branch
+git checkout -b feature/readthedocs-simplified
+
+# Implement all 4 phases on single branch
+# Commit after each phase for clarity
+
+# Final merge to master
+git checkout master
+git merge feature/readthedocs-simplified
+```
+
+### Commit Pattern
+- Phase 1: "fix: resolve doc8 linting errors blocking CI/CD"
+- Phase 2: "refactor: simplify documentation templates"
+- Phase 3: "feat: add basic ReadTheDocs configuration"
+- Phase 4: "test: validate documentation deployment"
+
+## 📂 Affected Areas
+
+### Files to Modify
+- Fix linting in existing RST files (Phase 1)
+- Simplify `docs/source/_templates/autosummary/` (Phase 2) 
+- Create `.readthedocs.yaml` (Phase 3)
+- Update build process documentation (Phase 4)
+
+### Files NOT Affected
+- No changes to solarwindpy source code
+- No changes to existing docstrings
+- No complex validation scripts
+- No advanced Sphinx configuration
+
+## ⚠️ Risk Mitigation
+
+### Technical Risks
+- **Template syntax errors**: Test thoroughly before deployment
+- **Build failures**: Incremental testing at each phase
+- **ReadTheDocs issues**: Use standard configuration patterns
+
+### Project Risks
+- **Feature requests for enhancements**: Document incremental enhancement path
+- **Maintenance concerns**: Keep complexity minimal
+- **Developer confusion**: Clear documentation of template system
+
+## 💡 Strategic Value
+
+### Immediate Benefits
+- **CI/CD unblocked**: Documentation builds work again
+- **ReadTheDocs deployment**: Professional documentation online
+- **Template preservation**: Customization capability maintained
+- **Quick delivery**: 2 hours to working documentation
+
+### Long-term Benefits
+- **Incremental enhancement**: Can add physics features later
+- **Maintainable system**: Simple, standard patterns
+- **Developer efficiency**: Fast build and deployment cycle
+- **Professional presentation**: Clean, working documentation
+
+### SolarWindPy-Specific Value
+- **Scientific software standards**: Professional documentation for research package
+- **User adoption**: Accessible documentation for plasma physicists
+- **Contributor onboarding**: Clear, working documentation system
+- **Package distribution**: Enhanced PyPI/Conda visibility
+
+## 🔗 Plan Consolidation
+
+### Superseded Plans
+This plan replaces and consolidates:
+1. **readthedocs-automation**: Over-engineered physics-aware approach
+2. **documentation-template-fix**: Core persistence insights preserved
+3. **documentation-workflow-fix**: Doc8 fixes integrated
+
+### Disposition
+- Move superseded plans to `plans/abandoned/`
+- Document why simplified approach is preferred
+- Preserve key insights for potential future enhancement
+
+---
+
+## 🚀 Implementation Timeline
+
+| Phase | Duration | Focus | Key Deliverable |
+|-------|----------|-------|----------------|
+| **Phase 1** | 10 min | Fix linting | CI/CD unblocked |
+| **Phase 2** | 30 min | Simplify templates | Persistence preserved |
+| **Phase 3** | 40 min | ReadTheDocs setup | Docs online |
+| **Phase 4** | 40 min | Test & validate | Production ready |
+
+**Total**: 2 hours for complete working documentation system
+
+---
+
+*This pragmatic plan delivers professional ReadTheDocs documentation quickly while preserving the essential template persistence capability that prevents lost customizations. It focuses on immediate value delivery over theoretical future requirements.*

plans/readthedocs-simplified/1-Immediate-Fixes.md

@@ -0,0 +1,216 @@
+# Phase 1: Immediate Doc8 Fixes
+
+## Phase Metadata
+- **Phase**: 1/4
+- **Estimated Duration**: 10 minutes
+- **Dependencies**: None (immediate fixes)
+- **Status**: Not Started
+
+## 🎯 Phase Objective
+Fix critical doc8 linting errors that are blocking all CI/CD documentation builds. These are simple formatting issues causing 100% build failure rate since August 16, 2025.
+
+## 🧠 Phase Context
+The documentation workflow has been failing consistently with doc8 linting errors. These are **not functional problems** but formatting violations that the strict linting configuration treats as build failures, blocking the entire documentation pipeline.
+
+## 📋 Current Doc8 Failures
+
+Based on the error pattern analysis, the current failures are:
+
+### Error Types Identified
+1. **D005: Missing newlines at EOF** (4 files)
+2. **D002: Trailing whitespace** (2 instances)  
+3. **D001: Line too long** (1 instance)
+
+### Impact Analysis
+- **Documentation updates blocked** for 4+ days
+- **PR merges delayed** due to failed status checks
+- **CI/CD pipeline disrupted** across all branches
+- **ReadTheDocs deployment impossible** until resolved
+
+## 🔧 Implementation Tasks
+
+### Task 1.1: Identify All Doc8 Violations (2 minutes)
+
+**Run comprehensive doc8 check**:
+```bash
+# From repository root
+cd docs
+doc8 source/ --max-line-length=88 --verbose
+```
+
+**Expected output**: List of all current violations with file paths and line numbers
+
+**Document findings**: Create list of files needing fixes with specific error types
+
+### Task 1.2: Fix Missing Newlines at EOF (3 minutes)
+
+**For each file missing newline at EOF**:
+```bash
+# Add newline to end of file
+echo "" >> path/to/file.rst
+```
+
+**Validation**:
+```bash
+# Check file ends with newline
+tail -c 1 path/to/file.rst | wc -l
+# Should output: 1
+```
+
+### Task 1.3: Remove Trailing Whitespace (2 minutes)
+
+**Remove trailing whitespace from identified files**:
+```bash
+# For each affected file
+sed -i 's/[[:space:]]*$//' path/to/file.rst
+```
+
+**Validation**:
+```bash
+# Check for trailing whitespace
+grep -n '[[:space:]]$' path/to/file.rst
+# Should output: nothing (no matches)
+```
+
+### Task 1.4: Fix Line Length Violations (2 minutes)
+
+**For lines exceeding 88 characters**:
+- Manual review and rewrap long lines
+- Break at logical points (after punctuation, before new clauses)
+- Maintain RST formatting integrity
+- Preserve any code blocks or literals
+
+**Example fix**:
+```rst
+# Before (too long)
+This is an extremely long line that exceeds the maximum allowed line length of 88 characters and needs to be wrapped appropriately.
+
+# After (properly wrapped)
+This is an extremely long line that exceeds the maximum allowed line length of 88 
+characters and needs to be wrapped appropriately.
+```
+
+### Task 1.5: Comprehensive Validation (1 minute)
+
+**Run final doc8 validation**:
+```bash
+cd docs
+doc8 source/ --max-line-length=88
+echo $?  # Should output: 0 (success)
+```
+
+**Test documentation build**:
+```bash
+make clean
+make html
+# Should complete without doc8-related errors
+```
+
+## ✅ Phase Acceptance Criteria
+
+### Technical Validation
+- [ ] `doc8 source/` returns exit code 0 (no errors)
+- [ ] All identified files pass doc8 checks individually
+- [ ] Documentation builds successfully with `make html`
+- [ ] No new doc8 violations introduced
+
+### Quality Assurance
+- [ ] RST syntax remains valid after fixes
+- [ ] No content or formatting corruption
+- [ ] Code blocks and literals preserved intact
+- [ ] Cross-references still functional
+
+### CI/CD Integration
+- [ ] GitHub Actions documentation workflow passes
+- [ ] All status checks green for documentation
+- [ ] No blocking errors in CI logs
+
+## 🧪 Phase Testing Strategy
+
+### Local Testing
+1. **Individual file validation**: Test each fixed file separately
+2. **Full build test**: Complete documentation build from clean state
+3. **Content verification**: Spot-check that fixes don't break content
+
+### CI/CD Testing
+1. **Push test branch**: Create test branch with fixes
+2. **Monitor workflow**: Verify GitHub Actions succeed
+3. **Check logs**: Confirm no doc8 errors in CI output
+
+## 📊 Expected Results
+
+### Before Phase 1
+- **Build success rate**: 0% (complete failure)
+- **Time to fix per build**: 30+ minutes manual debugging
+- **Developer frustration**: High (blocked PRs)
+- **Documentation freshness**: Stale (4+ days)
+
+### After Phase 1
+- **Build success rate**: 100% (unblocked)
+- **Time to fix per build**: 0 minutes (automated)
+- **Developer frustration**: Eliminated
+- **Documentation freshness**: Current (real-time updates)
+
+## 🔗 Phase Dependencies
+
+### Provides for Phase 2
+- **Clean build environment**: No linting errors blocking template work
+- **Working CI/CD**: Can test template changes safely
+- **Baseline functionality**: Documentation system operational
+
+### No Dependencies Required
+- This phase has no dependencies on other phases
+- Can be implemented immediately
+- Provides immediate value (unblocks CI/CD)
+
+## ⚠️ Risk Assessment
+
+### Low Risk Items
+- **Formatting fixes**: Non-functional changes only
+- **Standard tooling**: doc8 is well-established linter
+- **Reversible changes**: All fixes can be easily undone
+
+### Mitigation Strategies
+- **Test each fix individually**: Verify no content corruption
+- **Maintain RST validity**: Check syntax after each change
+- **Document changes**: Clear record of what was modified
+
+## 💬 Implementation Notes
+
+### Why These Fixes Matter
+1. **Immediate CI/CD unblocking**: Restores documentation pipeline
+2. **Foundation for next phases**: Cannot test templates with broken builds
+3. **Developer productivity**: Eliminates daily build failures
+4. **Professional standards**: Clean, consistent formatting
+
+### Quick Win Strategy
+- Focus on **minimum viable fixes** to unblock builds
+- **Don't over-engineer**: Just fix the specific violations
+- **Test incrementally**: Verify each fix before moving to next
+- **Document process**: For future maintenance
+
+---
+
+## Phase Completion
+
+### Commit Message
+```
+fix: resolve doc8 linting errors blocking CI/CD
+
+- Add missing newlines at EOF (4 files)
+- Remove trailing whitespace (2 instances)  
+- Fix line length violations (1 instance)
+- Restore 100% documentation build success rate
+
+Phase 1 of readthedocs-simplified plan: Immediate CI/CD unblocking
+```
+
+### Success Verification
+- [ ] `doc8 source/` passes cleanly
+- [ ] `make html` completes without errors
+- [ ] GitHub Actions documentation workflow succeeds
+- [ ] Ready to proceed to Phase 2 (Template Simplification)
+
+---
+
+*Phase 1 Priority: Unblock CI/CD immediately with minimal, targeted formatting fixes*