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

plans/readthedocs-simplified/2-Template-Simplification.md

@@ -0,0 +1,278 @@
+# Phase 2: Template Simplification
+
+## Phase Metadata
+- **Phase**: 2/4
+- **Estimated Duration**: 30 minutes
+- **Dependencies**: Phase 1 (clean doc8 validation)
+- **Status**: Not Started
+
+## 🎯 Phase Objective
+Preserve the essential template infrastructure for API documentation persistence while removing unnecessary complexity. Maintain the **only mechanism** for customizing ephemeral API documentation files.
+
+## 🧠 Phase Context
+
+### Why Templates Are Essential (Not Optional)
+The documentation build process works as follows:
+1. `sphinx-apidoc` generates RST files in `docs/source/api/` 
+2. These files are **ephemeral** (destroyed on every build)
+3. These files are **git-ignored** (line 75 in `.gitignore`)
+4. Templates provide the **only way** to customize these generated files
+
+**Without templates**: 100% of API documentation customizations are lost on every build.
+
+### Current Template Infrastructure
+```
+docs/source/_templates/autosummary/
+├── module.rst      # Template for module-level documentation
+└── class.rst       # Template for class-level documentation
+```
+
+**Post-processing**: `docs/add_no_index.py` adds `:no-index:` directives after generation.
+
+## 📋 Implementation Tasks
+
+### Task 2.1: Template Infrastructure Audit (5 minutes)
+
+**Examine current template system**:
+```bash
+cd docs/source/_templates/autosummary/
+ls -la
+cat module.rst
+cat class.rst
+```
+
+**Document current capabilities**:
+- Template syntax and variables available
+- Post-processing workflow integration
+- Sphinx configuration dependencies
+
+**Check build integration**:
+```bash
+cd docs
+grep -r "autosummary" source/conf.py
+grep -r "_templates" source/conf.py
+```
+
+### Task 2.2: Review Current Templates (10 minutes)
+
+**Analyze module.rst template**:
+```bash
+cd docs/source/_templates/autosummary/
+cat module.rst
+```
+
+**Current content** (as of audit):
+```rst
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+   :members:
+   :show-inheritance:
+   :undoc-members:
+   :no-index:
+```
+
+**Assess complexity level**:
+- ✅ **Simple, standard format** - Good baseline
+- ✅ **Essential directives present** - Maintains functionality
+- ✅ **No over-engineering** - Already simplified
+
+**Analyze class.rst template**:
+```bash
+cat class.rst
+```
+
+**Document any complexity** that should be simplified.
+
+### Task 2.3: Template Enhancement Strategy (10 minutes)
+
+**Keep Essential Elements**:
+1. **Basic template structure** - Required for persistence
+2. **Standard Sphinx directives** - `:members:`, `:show-inheritance:`
+3. **Post-processing compatibility** - `:no-index:` directive support
+
+**Remove/Avoid Complex Elements**:
+1. **Physics-specific sections** - Defer to future enhancement
+2. **Conditional logic** - Keep templates simple
+3. **Advanced formatting** - Standard autosummary sufficient
+4. **Custom validation** - Rely on Sphinx warnings
+
+**Document Template Usage**:
+Create `docs/template-usage.md` with:
+- How to customize API documentation
+- Template file locations and purpose
+- Build process integration
+- When to edit templates vs docstrings
+
+### Task 2.4: Post-Processing Validation (3 minutes)
+
+**Verify post-processing workflow**:
+```bash
+cd docs
+cat add_no_index.py
+```
+
+**Test post-processing script**:
+```bash
+# Generate API docs
+make api
+
+# Check that :no-index: is added
+grep -r "no-index" source/api/ | head -5
+```
+
+**Ensure integration works**:
+- Post-processing runs after template application
+- `:no-index:` directives added correctly
+- No conflicts with template customizations
+
+### Task 2.5: Template Documentation (2 minutes)
+
+**Create template usage guide**:
+
+**Target**: `docs/template-usage.md`
+
+```markdown
+# Template Usage Guide
+
+## Overview
+Templates in `docs/source/_templates/autosummary/` control the format of auto-generated API documentation.
+
+## Why Templates Matter
+- API files in `docs/source/api/` are ephemeral (regenerated on every build)
+- Templates provide the ONLY way to customize API documentation
+- Changes to templates persist across rebuilds
+
+## Template Files
+- `module.rst` - Controls module-level documentation format
+- `class.rst` - Controls class-level documentation format
+
+## Editing Process
+1. Edit template files in `docs/source/_templates/autosummary/`
+2. Run `make api` to regenerate API documentation
+3. Run `make html` to build full documentation
+4. Verify changes appear in generated documentation
+
+## Build Process
+1. `sphinx-apidoc` generates RST files using templates
+2. `add_no_index.py` post-processes files (adds :no-index:)
+3. Sphinx builds final HTML documentation
+
+## Important Notes
+- NEVER edit files in `docs/source/api/` directly (they're regenerated)
+- All API customizations must go in templates
+- Templates use Jinja2 syntax with Sphinx variables
+```
+
+## ✅ Phase Acceptance Criteria
+
+### Template Infrastructure
+- [ ] Existing templates preserved and functional
+- [ ] Template complexity remains minimal (no physics enhancements)
+- [ ] Post-processing integration working correctly
+- [ ] Template usage clearly documented
+
+### Build Process
+- [ ] `make api` generates API documentation using templates
+- [ ] `make html` builds complete documentation successfully
+- [ ] Post-processing adds `:no-index:` directives correctly
+- [ ] No template-related Sphinx warnings
+
+### Documentation Quality
+- [ ] Generated API documentation maintains professional quality
+- [ ] All modules and classes properly documented
+- [ ] Navigation and cross-references working
+- [ ] Consistent formatting across all API documentation
+
+## 🧪 Phase Testing Strategy
+
+### Template Persistence Test
+1. **Make template customization**: Add comment to module.rst
+2. **Regenerate documentation**: Run `make api && make html`
+3. **Verify persistence**: Confirm customization appears in generated docs
+4. **Repeat build**: Verify customization survives multiple rebuilds
+
+### Build Integration Test
+1. **Clean build**: `make clean && make api && make html`
+2. **Check for errors**: No template-related warnings
+3. **Verify output**: All API modules properly documented
+4. **Post-processing check**: `:no-index:` directives present
+
+## 📊 Expected Results
+
+### Template System Status
+- **Complexity**: Minimal (basic templates only)
+- **Functionality**: Full persistence capability preserved
+- **Maintainability**: Simple, standard patterns
+- **Documentation**: Clear usage guidelines
+
+### Build Performance
+- **Generation time**: Fast (no complex template processing)
+- **Error rate**: Low (simple templates, fewer failure points)
+- **Output quality**: Professional, consistent formatting
+
+## 🔗 Phase Dependencies
+
+### Requires from Phase 1
+- **Clean doc8 validation**: No linting errors blocking builds
+- **Working documentation build**: `make html` succeeds
+
+### Provides for Phase 3
+- **Stable template system**: ReadTheDocs can use templates reliably
+- **Documented process**: Clear understanding of customization workflow
+- **Baseline functionality**: API documentation generation working
+
+## ⚠️ Risk Assessment
+
+### Low Risk Elements
+- **Template preservation**: Existing system already works
+- **Minimal changes**: Avoiding complex modifications
+- **Standard patterns**: Using established Sphinx/autosummary features
+
+### Risk Mitigation
+- **Incremental testing**: Test each template change individually
+- **Backup current templates**: Save originals before any modifications
+- **Document all changes**: Clear record of modifications made
+
+## 💬 Implementation Notes
+
+### Simplification Philosophy
+1. **Preserve core functionality**: Templates must enable persistence
+2. **Avoid premature optimization**: Physics enhancements can wait
+3. **Standard patterns**: Use established Sphinx conventions
+4. **Clear documentation**: Enable future developers to understand system
+
+### Template Enhancement Path
+If physics-specific documentation is needed later:
+1. **Incremental addition**: Add features one at a time
+2. **Conditional logic**: Use template conditionals for module-specific content
+3. **Testing framework**: Validate enhancements don't break builds
+4. **Separate plan**: Major enhancements deserve their own implementation plan
+
+---
+
+## Phase Completion
+
+### Commit Message
+```
+refactor: simplify documentation templates for maintainability
+
+- Preserve essential template infrastructure for API doc persistence
+- Document template usage and customization process
+- Maintain post-processing integration (add_no_index.py)
+- Remove complex enhancements to focus on core functionality
+
+Phase 2 of readthedocs-simplified plan: Template system simplified
+```
+
+### Success Verification
+- [ ] Templates generate API documentation correctly
+- [ ] Post-processing adds `:no-index:` directives
+- [ ] Template customizations persist across rebuilds
+- [ ] Documentation build completes without template errors
+- [ ] Template usage guide created and accurate
+- [ ] Ready to proceed to Phase 3 (ReadTheDocs Setup)
+
+---
+
+*Phase 2 Priority: Maintain essential template persistence while keeping complexity minimal*

plans/readthedocs-simplified/3-ReadTheDocs-Setup.md

@@ -0,0 +1,298 @@
+# Phase 3: ReadTheDocs Setup
+
+## Phase Metadata
+- **Phase**: 3/4
+- **Estimated Duration**: 40 minutes
+- **Dependencies**: Phase 1 (clean builds), Phase 2 (working templates)
+- **Status**: Not Started
+
+## 🎯 Phase Objective
+Configure minimal ReadTheDocs integration to deploy SolarWindPy documentation online with standard HTML output. Focus on working deployment quickly rather than advanced features.
+
+## 🧠 Phase Context
+
+### ReadTheDocs Integration Strategy
+- **Minimal configuration**: Use standard, proven patterns
+- **HTML output only**: Skip PDF/EPUB for simplicity
+- **Manual setup**: Avoid complex webhook automation initially
+- **Standard theme**: Use sphinx_rtd_theme (ReadTheDocs default)
+
+### What We're NOT Building
+- ❌ **Multiple output formats** (PDF/EPUB) - HTML sufficient
+- ❌ **Complex build hooks** - Standard Python package build
+- ❌ **Advanced webhook integration** - Manual deployment acceptable
+- ❌ **Custom styling** - Default theme works fine
+
+## 📋 Implementation Tasks
+
+### Task 3.1: ReadTheDocs Configuration File (15 minutes)
+
+**Create minimal `.readthedocs.yaml`**:
+
+**Target**: `.readthedocs.yaml` (repository root)
+
+```yaml
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - requirements: requirements.txt
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+
+sphinx:
+  configuration: docs/source/conf.py
+  builder: html
+```
+
+**Configuration rationale**:
+- **Ubuntu 22.04**: Latest stable ReadTheDocs environment
+- **Python 3.11**: Modern Python version with good package compatibility
+- **requirements.txt**: Standard package dependencies
+- **docs/requirements.txt**: Documentation-specific dependencies
+- **HTML builder only**: Simplest, most reliable output format
+
+### Task 3.2: Documentation Requirements File (5 minutes)
+
+**Check if `docs/requirements.txt` exists**:
+```bash
+ls -la docs/requirements.txt
+```
+
+**If missing, create `docs/requirements.txt`**:
+```txt
+sphinx>=4.0
+sphinx-rtd-theme
+```
+
+**If exists, verify contents include**:
+- sphinx (version 4.0 or higher)
+- sphinx-rtd-theme
+- Any other documentation dependencies
+
+**Validate requirements**:
+```bash
+pip install -r docs/requirements.txt
+```
+
+### Task 3.3: Sphinx Configuration for ReadTheDocs (10 minutes)
+
+**Check current `docs/source/conf.py` for ReadTheDocs compatibility**:
+
+**Add ReadTheDocs detection (if not present)**:
+```python
+import os
+
+# ReadTheDocs environment detection
+on_rtd = os.environ.get('READTHEDOCS') == 'True'
+
+if on_rtd:
+    # ReadTheDocs-specific settings
+    html_theme = 'sphinx_rtd_theme'
+else:
+    # Local development (use same theme for consistency)
+    html_theme = 'sphinx_rtd_theme'
+```
+
+**Verify essential configuration**:
+```python
+# Ensure these settings exist
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',  # If using NumPy/Google docstrings
+]
+
+autosummary_generate = True
+```
+
+**Test configuration locally**:
+```bash
+cd docs
+make clean
+make html
+# Should build successfully with sphinx_rtd_theme
+```
+
+### Task 3.4: Manual ReadTheDocs Project Setup (10 minutes)
+
+**ReadTheDocs account setup steps**:
+
+1. **Access ReadTheDocs**:
+   - Go to https://readthedocs.org/dashboard/import/
+   - Sign in with GitHub account
+
+2. **Import repository**:
+   - Select SolarWindPy repository from GitHub
+   - Use repository URL: https://github.com/space-physics/solarwindpy
+   - Or appropriate repository URL
+
+3. **Project configuration**:
+   ```
+   Project name: solarwindpy
+   Project slug: solarwindpy
+   Repository URL: [GitHub URL]
+   Default branch: master
+   Language: English
+   Programming language: Python
+   ```
+
+4. **Build settings**:
+   ```
+   Configuration file: .readthedocs.yaml
+   Documentation type: Sphinx Html
+   Python version: 3.11
+   ```
+
+5. **Advanced settings**:
+   ```
+   Install project: Yes
+   Requirements file: requirements.txt
+   Python interpreter: CPython 3.11
+   ```
+
+**Manual verification needed** (cannot be automated):
+- ReadTheDocs account access required
+- GitHub repository permissions
+- Manual configuration through web interface
+
+## ✅ Phase Acceptance Criteria
+
+### Configuration Files
+- [ ] `.readthedocs.yaml` created with minimal, working configuration
+- [ ] `docs/requirements.txt` exists with necessary dependencies
+- [ ] `docs/source/conf.py` compatible with ReadTheDocs environment
+- [ ] Local build succeeds with ReadTheDocs-compatible settings
+
+### ReadTheDocs Integration
+- [ ] ReadTheDocs project created and configured
+- [ ] Repository successfully imported
+- [ ] Initial build triggered and monitored
+- [ ] HTML documentation accessible online
+
+### Build Verification
+- [ ] ReadTheDocs build completes without critical errors
+- [ ] Generated documentation displays correctly
+- [ ] Navigation and search functionality working
+- [ ] API documentation appears in online version
+
+## 🧪 Phase Testing Strategy
+
+### Local ReadTheDocs Simulation
+1. **Environment test**: Use Python 3.11 in clean environment
+2. **Dependency test**: Install from requirements.txt only
+3. **Build test**: Generate documentation with sphinx_rtd_theme
+4. **Output verification**: Check HTML output matches expectations
+
+### ReadTheDocs Platform Testing
+1. **Manual build trigger**: Initiate first build through web interface
+2. **Build log review**: Check for errors or warnings in ReadTheDocs logs
+3. **Output verification**: Access generated documentation URL
+4. **Navigation test**: Verify all sections accessible
+
+## 📊 Expected Results
+
+### Local Build Performance
+- **Build time**: < 5 minutes for complete documentation
+- **Output quality**: Professional appearance with sphinx_rtd_theme
+- **Error rate**: Zero critical errors, minimal warnings
+- **Functionality**: All links and navigation working
+
+### ReadTheDocs Deployment
+- **Deployment URL**: https://solarwindpy.readthedocs.io/
+- **Update mechanism**: Manual builds initially (webhook setup optional)
+- **Build success rate**: 100% for basic HTML generation
+- **Documentation freshness**: Updated when manually triggered
+
+## 🔗 Phase Dependencies
+
+### Requires from Previous Phases
+- **Phase 1**: Clean doc8 validation (no linting blocking builds)
+- **Phase 2**: Working template system (API documentation generation)
+
+### Provides for Phase 4
+- **ReadTheDocs project**: Configured and accessible
+- **Build baseline**: Known working configuration
+- **Deployment target**: URL for testing and validation
+
+## ⚠️ Risk Assessment
+
+### Configuration Risks
+- **Dependency conflicts**: requirements.txt incompatibility
+- **Sphinx version issues**: Newer/older versions causing problems
+- **Theme compatibility**: sphinx_rtd_theme integration issues
+
+### Platform Risks
+- **ReadTheDocs account access**: May require permissions setup
+- **Repository permissions**: GitHub integration configuration
+- **Build environment**: ReadTheDocs platform changes
+
+### Mitigation Strategies
+- **Test locally first**: Verify configuration works before ReadTheDocs
+- **Standard dependencies**: Use well-established package versions
+- **Incremental debugging**: Address one issue at a time
+
+## 💬 Implementation Notes
+
+### Minimal Configuration Philosophy
+1. **Use defaults where possible**: ReadTheDocs has good standard settings
+2. **Avoid premature optimization**: Advanced features can be added later
+3. **Focus on reliability**: Working deployment is priority #1
+4. **Document assumptions**: Make configuration decisions explicit
+
+### ReadTheDocs Platform Notes
+- **Build time limits**: Free accounts have build time restrictions
+- **Concurrent builds**: May queue behind other projects
+- **Environment consistency**: ReadTheDocs controls build environment
+- **Debugging access**: Build logs available through web interface
+
+### Future Enhancement Path
+If advanced features are needed later:
+1. **PDF/EPUB output**: Add to .readthedocs.yaml formats section
+2. **Webhook automation**: Configure GitHub integration
+3. **Custom domain**: Set up custom documentation URL
+4. **Build optimization**: Add caching and dependency optimization
+
+---
+
+## Phase Completion
+
+### Commit Message
+```
+feat: add basic ReadTheDocs configuration
+
+- Create minimal .readthedocs.yaml for HTML documentation
+- Ensure docs/requirements.txt includes necessary dependencies
+- Configure Sphinx for ReadTheDocs compatibility
+- Document manual ReadTheDocs project setup process
+
+Phase 3 of readthedocs-simplified plan: ReadTheDocs deployment ready
+```
+
+### Success Verification
+- [ ] `.readthedocs.yaml` committed to repository root
+- [ ] `docs/requirements.txt` contains sphinx and sphinx_rtd_theme
+- [ ] Local documentation builds with ReadTheDocs-compatible settings
+- [ ] ReadTheDocs project configured and first build attempted
+- [ ] Documentation accessible at readthedocs.io URL
+- [ ] Ready to proceed to Phase 4 (Testing & Validation)
+
+### Manual Setup Documentation
+**Record ReadTheDocs project details for reference**:
+```
+Project URL: https://readthedocs.org/projects/solarwindpy/
+Documentation URL: https://solarwindpy.readthedocs.io/
+Build status: [Record first build result]
+Configuration: Using .readthedocs.yaml from repository
+```
+
+---
+
+*Phase 3 Priority: Get working documentation online with minimal configuration complexity*