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

plans/abandoned/readthedocs-automation/0-Overview.md

@@ -0,0 +1,247 @@
+# ReadTheDocs Automation Implementation Plan - Overview
+
+## Plan Metadata
+- **Plan Name**: ReadTheDocs Automation Implementation
+- **Created**: 2025-08-19
+- **Branch**: plan/readthedocs-automation
+- **Implementation Branch**: feature/readthedocs-automation
+- **Coordinator**: UnifiedPlanCoordinator
+- **Structure**: Multi-Phase (4 phases)
+- **Total Phases**: 4
+- **Dependencies**: None
+- **Affects**: Documentation system, ReadTheDocs integration, existing documentation plans
+- **Estimated Duration**: 10 hours
+- **Status**: Planning
+
+## Phase Overview
+- [ ] **Phase 1: Emergency Documentation Fixes** (Est: 10 minutes) - Fix doc8 linting errors blocking builds
+- [ ] **Phase 2: Template System Enhancement** (Est: 4-6 hours) - Implement physics-aware template system
+- [ ] **Phase 3: Quality Audit & ReadTheDocs Integration** (Est: 2-3 hours) - Automation setup and quality validation
+- [ ] **Phase 4: Plan Consolidation & Cleanup** (Est: 2 hours) - Audit existing plans and cleanup
+
+## Phase Files
+1. [1-Emergency-Documentation-Fixes.md](./1-Emergency-Documentation-Fixes.md)
+2. [2-Template-System-Enhancement.md](./2-Template-System-Enhancement.md)
+3. [3-Quality-Audit-ReadTheDocs-Integration.md](./3-Quality-Audit-ReadTheDocs-Integration.md)
+4. [4-Plan-Consolidation-Cleanup.md](./4-Plan-Consolidation-Cleanup.md)
+
+## 🎯 Objective
+Implement automated ReadTheDocs documentation deployment with zero manual RST editing through:
+1. **Template-based customization** - All changes through persistent templates
+2. **Automated pipeline** - Push to master triggers ReadTheDocs builds
+3. **Physics-aware documentation** - Scientific context in generated docs
+4. **Plan consolidation** - Single source of truth replacing 4 existing plans
+
+## 🧠 Context
+SolarWindPy currently has:
+- **Critical blocker**: doc8 linting errors preventing all documentation builds
+- **Template foundation**: Existing but underutilized template system
+- **ReadTheDocs configuration**: `.readthedocs.yaml` already configured
+- **Multiple documentation plans**: 4 overlapping plans need consolidation
+
+This unified plan addresses all issues through a single, comprehensive implementation.
+
+## 🔧 Git Workflow
+
+### Branch Structure
+```bash
+# Initial setup
+git checkout -b plan/readthedocs-automation      # Planning branch
+git checkout -b feature/readthedocs-automation   # Single development branch
+```
+
+### Development Flow
+All 4 phases executed on **single feature branch**:
+- No branch switching between phases
+- Compaction at each phase boundary
+- Continuous development context
+
+### Phase Completion Pattern
+```bash
+# At end of each phase
+git add -A && git commit -m "phase message"
+python .claude/hooks/create-compaction.py  # Phase boundary compaction
+# Continue on same branch for next phase
+```
+
+### Final Merge Workflow
+```bash
+# After Phase 4 completion
+git checkout plan/readthedocs-automation
+git merge feature/readthedocs-automation
+
+# Move plan to completed
+mkdir -p plans/completed/readthedocs-automation
+cp -r plans/readthedocs-automation/* plans/completed/readthedocs-automation/
+git add -A && git commit -m "docs: archive completed readthedocs-automation plan"
+
+# Create PR to master
+gh pr create --title "feat: automated ReadTheDocs deployment system"
+```
+
+## 🔄 Compaction Strategy
+
+### Phase Boundary Compactions
+- **Phase 1 → 2**: Emergency fixes compaction
+- **Phase 2 → 3**: Template system compaction  
+- **Phase 3 → 4**: Integration compaction
+- **Phase 4 complete**: Final plan completion compaction
+
+### Git Tags
+Each compaction creates tags:
+- `claude/compaction/readthedocs-phase-1`
+- `claude/compaction/readthedocs-phase-2`
+- `claude/compaction/readthedocs-phase-3`
+- `claude/compaction/readthedocs-phase-4`
+
+## 📂 Affected Areas
+
+### Primary Changes
+- `docs/source/*.rst` - Fix linting errors
+- `docs/source/_templates/autosummary/` - Enhanced templates
+- `docs/conf.py` - Sphinx configuration updates
+- `.readthedocs.yaml` - ReadTheDocs automation configuration
+- Existing documentation plans - Consolidation and archival
+
+### Infrastructure
+- GitHub Actions workflows - Documentation builds
+- ReadTheDocs webhook - Automated deployment
+- Template processing - Physics-aware content generation
+
+## ✅ Acceptance Criteria
+
+### Technical Requirements
+- [ ] Zero doc8 linting errors
+- [ ] Template-based documentation system operational
+- [ ] ReadTheDocs automated deployment working
+- [ ] Zero manual RST editing required
+- [ ] Physics-aware documentation sections
+
+### Plan Management
+- [ ] All 4 existing documentation plans audited
+- [ ] Superseded plans moved to abandoned/
+- [ ] Follow-up plan created if needed
+- [ ] Single source of truth established
+
+### Quality Standards
+- [ ] Professional HTML rendering
+- [ ] Sphinx warnings eliminated
+- [ ] Cross-references working
+- [ ] Scientific documentation quality
+
+## 🧪 Testing Strategy
+
+### Phase 1 Testing
+- doc8 validation passes
+- Documentation builds successfully
+- GitHub Actions unblocked
+
+### Phase 2 Testing
+- Template changes persist across rebuilds
+- Physics sections appear in generated docs
+- Build system integration works
+
+### Phase 3 Testing
+- ReadTheDocs webhook functions
+- Automated deployment works
+- Quality validation passes
+
+### Phase 4 Testing
+- Plan consolidation complete
+- No orphaned documentation issues
+- Clear project state
+
+## 📊 Progress Tracking
+
+### Overall Status
+- **Phases Completed**: 0/4
+- **Time Invested**: 0h of 10h
+- **Current Phase**: Planning
+- **Next Action**: Begin Phase 1
+
+### Implementation Notes
+[Running log of implementation decisions, blockers, changes]
+
+## 🔗 Plan Consolidation
+
+### Existing Plans to Audit
+1. **documentation-workflow-fix**: 
+   - Status: Active, immediate fixes needed
+   - Expected: Fully addressed by Phase 1
+   
+2. **documentation-template-fix**:
+   - Status: Active, template persistence issues  
+   - Expected: Fully addressed by Phase 2
+   
+3. **documentation-rendering-fixes**:
+   - Status: Active, quality improvements
+   - Expected: Partially addressed, may need follow-up
+   
+4. **documentation-rebuild-session**:
+   - Status: Completed session
+   - Expected: Archive as completed
+
+### Disposition Strategy
+- **Fully addressed plans** → Move to `plans/abandoned/` with completion note
+- **Partially addressed plans** → Create follow-up plan with remaining work
+- **Completed plans** → Acknowledge and reference in completion notes
+
+## 💡 Success Metrics
+
+### Immediate (Phase 1)
+- ✅ Documentation builds pass
+- ✅ GitHub Actions unblocked
+- ✅ ReadTheDocs builds resume
+
+### Short-term (Phase 2-3)
+- ✅ Template changes persist
+- ✅ Physics documentation generated
+- ✅ Automated deployment working
+
+### Long-term (Phase 4+)
+- ✅ Single documentation workflow
+- ✅ No manual RST editing needed
+- ✅ Consolidated plan ecosystem
+
+## ⚠️ Risk Mitigation
+
+### Technical Risks
+- **Build system breakage** → Incremental testing, rollback procedures
+- **Template complexity** → Start simple, iterate
+- **ReadTheDocs integration** → Test webhook thoroughly
+
+### Project Risks
+- **Plan consolidation errors** → Careful audit, preserve important work
+- **Lost requirements** → Document all superseded functionality
+- **Developer confusion** → Clear documentation, transition plan
+
+## 🎯 Strategic Value
+
+### ReadTheDocs Automation Benefits
+- **Zero maintenance** - Push to master triggers deployment
+- **Professional quality** - Template-based consistency
+- **Scientific focus** - Physics-aware documentation
+- **Developer efficiency** - No manual RST editing
+
+### Plan Management Benefits
+- **Single source of truth** - No conflicting documentation plans
+- **Clear project state** - Consolidated requirements
+- **Reduced complexity** - 4 plans → 1 comprehensive solution
+- **Future efficiency** - Template-based scalability
+
+---
+
+## 🚀 Implementation Timeline
+
+| Phase | Duration | Focus | Compaction |
+|-------|----------|-------|------------|
+| **Phase 1** | 10 min | Fix doc8 errors | ✅ |
+| **Phase 2** | 4-6 hours | Template system | ✅ |
+| **Phase 3** | 2-3 hours | ReadTheDocs integration | ✅ |
+| **Phase 4** | 2 hours | Plan consolidation | ✅ |
+
+**Total**: ~10 hours across single feature branch with phase boundary compactions
+
+---
+
+*This comprehensive plan transforms SolarWindPy's documentation system from a fragmented, manually-intensive process to an automated, template-based, physics-aware documentation pipeline with ReadTheDocs integration.*

plans/abandoned/readthedocs-automation/1-Emergency-Documentation-Fixes.md

@@ -0,0 +1,270 @@
+# Phase 1: Emergency Documentation Fixes
+
+## Objective
+Immediately resolve all doc8 linting errors blocking the documentation pipeline to restore CI/CD functionality and enable ReadTheDocs builds.
+
+## Critical Context
+**BLOCKING ISSUE**: 100% documentation build failure since August 16, 2025 due to doc8 linting errors. This phase provides immediate unblocking in 5-10 minutes.
+
+## Current Error State
+
+### Failed Build Summary
+```
+Total files scanned = 12
+Total accumulated errors = 7
+```
+
+### Error Breakdown
+1. **Missing newline at end of file (D005)** - 4 occurrences
+2. **Trailing whitespace (D002)** - 2 occurrences  
+3. **Line too long (D001)** - 1 occurrence
+
+### Affected Files
+- `docs/source/api_reference.rst`
+- `docs/source/index.rst`
+- `docs/source/_templates/autosummary/module.rst`
+- `docs/source/_templates/autosummary/class.rst`
+
+## Implementation Steps
+
+### Git Setup
+```bash
+# Already on feature/readthedocs-automation branch
+pwd  # Verify: /Users/balterma/observatories/code/SolarWindPy
+git status  # Confirm on feature/readthedocs-automation
+```
+
+### Step 1.1: Fix Missing Newlines (2 minutes)
+
+**Files requiring newline at EOF**:
+1. `docs/source/api_reference.rst` (line 9)
+2. `docs/source/index.rst` (line 34)
+3. `docs/source/_templates/autosummary/module.rst` (line 7)
+4. `docs/source/_templates/autosummary/class.rst` (line 29)
+
+**Implementation approach**:
+```bash
+# Automated approach
+for file in docs/source/api_reference.rst \
+           docs/source/index.rst \
+           docs/source/_templates/autosummary/module.rst \
+           docs/source/_templates/autosummary/class.rst; do
+    # Add newline if missing
+    [ -n "$(tail -c 1 "$file")" ] && echo >> "$file"
+done
+```
+
+**Manual verification**:
+- Open each file in editor
+- Navigate to end of file
+- Ensure cursor is on a new empty line
+- Save file
+
+### Step 1.2: Remove Trailing Whitespace (1 minute)
+
+**File**: `docs/source/index.rst`
+- **Line 17**: Remove trailing spaces after "API Reference"
+- **Line 23**: Remove trailing spaces after "Development"
+
+**Current problematic content** (lines 15-25):
+```rst
+.. toctree::
+   :maxdepth: 3
+   :caption: API Reference   ← trailing spaces here
+   
+   api_reference
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Development     ← trailing spaces here
+   
+   documentation_review
+```
+
+**Implementation**:
+```bash
+# Remove all trailing whitespace from index.rst
+sed -i 's/[[:space:]]*$//' docs/source/index.rst
+```
+
+### Step 1.3: Fix Line Length (2 minutes)
+
+**File**: `docs/source/index.rst`
+- **Line 4**: Line exceeds 79-80 character limit
+
+**Current content** (line 4):
+```rst
+SolarWindPy is a comprehensive toolkit for analyzing solar wind plasma and magnetic field data.
+```
+*96 characters - exceeds typical RST limit*
+
+**Fixed content**:
+```rst
+SolarWindPy is a comprehensive toolkit for analyzing solar wind plasma and
+magnetic field data.
+```
+
+**Implementation**:
+- Open `docs/source/index.rst`
+- Navigate to line 4
+- Break line after "and"
+- Ensure proper RST formatting maintained
+
+## Validation Steps
+
+### Step 1.4: Local Validation
+
+**Pre-commit validation**:
+```bash
+# Install doc8 if not present
+pip install doc8
+
+# Validate specific files
+doc8 docs/source/api_reference.rst \
+     docs/source/index.rst \
+     docs/source/_templates/autosummary/module.rst \
+     docs/source/_templates/autosummary/class.rst
+
+# Validate entire docs directory (excluding generated API)
+doc8 README.rst docs CITATION.rst --ignore-path docs/source/api
+```
+
+**Expected output**:
+```
+Total files scanned = 12
+Total accumulated errors = 0
+```
+
+### Step 1.5: Build Validation
+
+**Test documentation build**:
+```bash
+cd docs
+make clean
+make html
+```
+
+**Expected result**: 
+- Build completes without errors
+- No doc8 failures in output
+- HTML files generated successfully
+
+## Phase Completion
+
+### Commit Changes
+```bash
+# Add all documentation fixes
+git add docs/source/api_reference.rst \
+        docs/source/index.rst \
+        docs/source/_templates/autosummary/module.rst \
+        docs/source/_templates/autosummary/class.rst
+
+# Commit with descriptive message
+git commit -m "fix: resolve doc8 linting errors blocking documentation builds
+
+- Add missing newlines at EOF for 4 RST files (D005 errors)
+- Remove trailing whitespace from index.rst lines 17, 23 (D002 errors)  
+- Fix line length issue on index.rst line 4 (D001 error)
+- Unblocks documentation workflow failing since Aug 16
+
+Resolves all 7 doc8 errors:
+- 4x D005 (no newline at end of file)
+- 2x D002 (trailing whitespace)
+- 1x D001 (line too long)
+
+Phase 1 of ReadTheDocs automation implementation."
+```
+
+### Create Phase Boundary Compaction
+```bash
+# Create compaction for phase transition
+python .claude/hooks/create-compaction.py
+```
+
+This creates git tag: `claude/compaction/readthedocs-phase-1`
+
+## Success Criteria
+
+### Must Pass
+- [ ] All 4 files have newlines at EOF
+- [ ] No trailing whitespace in any files
+- [ ] Line 4 of index.rst within length limits
+- [ ] doc8 returns 0 errors when run
+- [ ] Documentation builds successfully with `make html`
+- [ ] GitHub Actions documentation check passes
+
+### Validation Commands
+```bash
+# Final comprehensive validation
+doc8 README.rst docs CITATION.rst --ignore-path docs/source/api
+echo "Exit code: $?"  # Should be 0
+
+# Build validation
+cd docs && make clean && make html
+echo "Build exit code: $?"  # Should be 0
+```
+
+## Expected Immediate Results
+
+### Build Pipeline
+- ✅ Documentation workflow passes in GitHub Actions
+- ✅ GitHub Pages deployment resumes
+- ✅ All PRs show passing documentation check
+- ✅ ReadTheDocs builds can proceed
+
+### Metrics
+- **Build success rate**: 0% → 100%
+- **Time to deploy docs**: ∞ (blocked) → 5 minutes
+- **Developer friction**: High (failed checks) → None
+- **CI/CD resource waste**: 100% → 0%
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| Break RST syntax | Very Low (2%) | Medium | Local testing, simple formatting changes |
+| Miss a hidden error | Low (5%) | Low | Comprehensive doc8 run |
+| Git merge conflicts | Low (10%) | Low | Clean workspace, atomic commits |
+
+## Rollback Plan
+
+If any issues arise:
+```bash
+# Revert all changes
+git checkout HEAD~1 -- docs/source/api_reference.rst \
+                      docs/source/index.rst \
+                      docs/source/_templates/autosummary/module.rst \
+                      docs/source/_templates/autosummary/class.rst
+
+# Test that original errors return
+doc8 docs/source/index.rst  # Should show original 7 errors
+```
+
+## Next Phase Preparation
+
+After successful Phase 1 completion:
+1. **Verify GitHub Actions pass** - Check next automatic workflow run
+2. **Confirm ReadTheDocs accessibility** - Ensure builds can proceed
+3. **Document baseline state** - Clean foundation for template work
+4. **Proceed to Phase 2** - Template system enhancement
+
+Phase 1 creates the stable foundation required for all subsequent template and integration work.
+
+---
+
+## Time and Resource Summary
+
+| Task | Duration | Tools Required | Risk Level |
+|------|----------|---------------|------------|
+| Fix newlines | 2 min | Text editor/sed | Minimal |
+| Fix whitespace | 1 min | sed/editor | Minimal |
+| Fix line length | 2 min | Text editor | Minimal |
+| Validation | 2 min | doc8, make | Minimal |
+| Git operations | 3 min | git, compaction hook | Minimal |
+| **Total Phase 1** | **10 min** | Basic tools | **Minimal** |
+
+**Value delivered**: Unblocks entire documentation pipeline in 10 minutes
+**ROI**: 11,560% return in first year (from workflow-fix analysis)
+**Critical path**: Essential for all subsequent phases
+
+This phase transforms a complete documentation system failure into a fully operational foundation for automated ReadTheDocs deployment.