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

plans/documentation-template-fix/1-Template-System-Analysis.md

@@ -0,0 +1,269 @@
+# Phase 1: Template System Analysis
+
+## Objective
+Comprehensive analysis of the current Sphinx template system to understand capabilities, identify gaps, and plan enhancements for physics-specific documentation needs.
+
+## Current State Assessment
+
+### Template Directory Structure
+```
+docs/source/_templates/autosummary/
+├── class.rst          # Class documentation template
+└── module.rst         # Module documentation template
+```
+
+### Template Analysis
+
+#### Module Template (`docs/source/_templates/autosummary/module.rst`)
+**Current Implementation**:
+```rst
+{{ fullname | escape | underline }}
+
+.. automodule:: {{ fullname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :no-index:
+```
+
+**Capabilities**:
+- ✅ Basic module documentation
+- ✅ Member enumeration
+- ✅ Inheritance tracking
+- ✅ No-index directive (prevents duplicate entries)
+
+**Limitations**:
+- ❌ No physics-specific sections
+- ❌ No custom formatting for scientific content
+- ❌ No mathematical notation enhancements
+- ❌ No units/constants documentation
+
+#### Class Template (`docs/source/_templates/autosummary/class.rst`)
+**Current Implementation**:
+```rst
+{{ fullname | escape | underline }}
+
+.. autoclass:: {{ fullname }}
+   :members:
+   :show-inheritance:
+   :no-index:
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {{ item }}
+   {%- endfor %}
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+```
+
+**Capabilities**:
+- ✅ Structured class documentation
+- ✅ Separate methods and attributes sections
+- ✅ Inheritance display
+- ✅ Summary tables for methods/attributes
+
+**Limitations**:
+- ❌ No physics property sections (e.g., derived quantities)
+- ❌ No unit documentation for attributes
+- ❌ No physics validation information
+- ❌ No mathematical relationships
+
+### Build Pipeline Analysis
+
+#### Sphinx Configuration (`docs/source/conf.py`)
+**Key Settings**:
+- `autosummary_generate = True` (line 51) - Enables RST generation
+- `autosummary_generate_overwrite = True` (line 53) - Allows template overrides
+- `templates_path = ['_templates']` (line 46) - Template directory
+- Extensions: `sphinx.ext.autodoc`, `sphinx.ext.autosummary`, `numpydoc`
+
+#### Build Process (`docs/Makefile`)
+**Pipeline Flow**:
+1. `make api` → `sphinx-apidoc` generates RST files using templates
+2. `add_no_index.py` → Post-processes generated files
+3. `make html` → Sphinx builds HTML from processed RST files
+
+#### Post-Processing Script (`docs/add_no_index.py`)
+**Current Function**:
+- Adds `:no-index:` directive to automodule directives
+- Prevents duplicate index entries
+- Processes all files in `docs/source/api/`
+
+**Regex Pattern**: `r'(\.\. automodule:: .+?)(\n   :members:)'`
+**Replacement**: Inserts `:no-index:` directive
+
+### Generated Content Analysis
+
+#### API Directory Contents (`docs/source/api/`)
+**File Count**: 52 files (as of current analysis)
+**File Types**:
+- **Module files**: `solarwindpy.core.plasma.rst`, `solarwindpy.plotting.base.rst`, etc.
+- **Package files**: `solarwindpy.core.rst`, `solarwindpy.plotting.rst`, etc.
+- **Root file**: `modules.rst` (main API entry point)
+
+**Generation Command**:
+```bash
+sphinx-apidoc -f -o $(SOURCEDIR)/api ../../solarwindpy/solarwindpy --separate
+```
+
+**Key Parameters**:
+- `-f`: Force overwrite of existing files
+- `-o`: Output directory
+- `--separate`: Create separate files for each module/package
+
+### Current Template Effectiveness
+
+#### Strengths
+1. **Functional Base System**: Templates work correctly with Sphinx
+2. **Proper Integration**: Builds complete without errors
+3. **Consistent Structure**: All modules follow same format
+4. **Post-Processing**: Automated `:no-index:` addition works
+5. **CI/CD Compatible**: GitHub Actions builds successfully
+
+#### Gaps for Scientific Software
+1. **Physics Context Missing**: No domain-specific documentation sections
+2. **Units Not Highlighted**: Physical quantities lack unit documentation
+3. **Mathematical Relationships**: No support for physics formulas
+4. **Validation Information**: No physics constraint documentation
+5. **Research Context**: Missing scientific background sections
+
+## Enhancement Opportunities
+
+### Identified Enhancement Areas
+
+#### 1. Physics-Aware Class Template
+**Potential Additions**:
+- **Physical Properties** section for derived quantities
+- **Units & Dimensions** section for attribute documentation
+- **Physics Constraints** section for validation rules
+- **Mathematical Relationships** section for formula documentation
+
+#### 2. Scientific Module Template
+**Potential Additions**:
+- **Physics Background** section for scientific context
+- **Key Equations** section for mathematical foundations
+- **Validation Rules** section for physical constraints
+- **Usage Examples** section with physics applications
+
+#### 3. Function Template (New)
+**Need Assessment**: Currently no dedicated function template
+**Potential Benefits**:
+- Specialized documentation for standalone functions
+- Physics formula documentation
+- Unit conversion function documentation
+
+#### 4. Package Template Enhancement
+**Current State**: Uses default Sphinx package template
+**Potential Improvements**:
+- Physics domain overview
+- Inter-module relationship documentation
+- Comprehensive physics workflow examples
+
+### Template System Capabilities
+
+#### Jinja2 Template Features Available
+- **Variables**: `{{ fullname }}`, `{{ objname }}`, `{{ underline }}`
+- **Lists**: `{{ methods }}`, `{{ attributes }}`
+- **Conditionals**: `{% if %}` for optional sections
+- **Loops**: `{% for %}` for member iteration
+- **Filters**: `escape`, `underline` for formatting
+
+#### Sphinx Integration Points
+- **Directives**: `automodule`, `autoclass`, `autofunction`
+- **Options**: `:members:`, `:undoc-members:`, `:show-inheritance:`
+- **Cross-references**: `:py:class:`, `:py:func:`, `:py:meth:`
+- **Custom sections**: `.. rubric::` for section headers
+
+## Gap Analysis for SolarWindPy
+
+### Critical Missing Features
+
+#### 1. Physics Documentation Support
+**Current**: Generic programming documentation
+**Needed**: Domain-specific physics documentation
+**Impact**: Medium - affects scientific usability
+
+#### 2. Mathematical Notation Enhancement
+**Current**: Basic text documentation
+**Needed**: LaTeX math support in templates
+**Impact**: High - essential for physics software
+
+#### 3. Units and Dimensions Integration
+**Current**: No unit documentation
+**Needed**: Automatic unit extraction and display
+**Impact**: High - critical for scientific accuracy
+
+#### 4. Validation Documentation
+**Current**: No constraint documentation
+**Needed**: Physics validation rule documentation
+**Impact**: Medium - improves software reliability
+
+### Technical Feasibility Assessment
+
+#### Template Enhancements
+**Complexity**: Low to Medium
+**Risk**: Low (templates are isolated from build system)
+**Timeline**: 2-4 hours for comprehensive enhancements
+
+#### Build System Integration
+**Complexity**: Low
+**Risk**: Low (post-processing already exists)
+**Timeline**: 1-2 hours for additional processing
+
+#### Sphinx Configuration
+**Complexity**: Low
+**Risk**: Low (existing configuration is stable)
+**Timeline**: 30 minutes for additional extensions
+
+## Recommendations for Phase 2
+
+### Priority Enhancements
+
+#### High Priority
+1. **Enhance class template** with physics-specific sections
+2. **Add mathematical notation support** for formulas
+3. **Create function template** for standalone physics functions
+
+#### Medium Priority
+1. **Enhance module template** with scientific context
+2. **Add units documentation** extraction
+3. **Create package overview** enhancements
+
+#### Low Priority
+1. **Advanced cross-referencing** for physics relationships
+2. **Custom CSS styling** for scientific documentation
+3. **Integration with external** physics databases
+
+### Success Criteria for Analysis Phase
+
+- [x] **Template inventory complete**: All current templates catalogued
+- [x] **Build pipeline understood**: Complete flow documented
+- [x] **Gap analysis complete**: Enhancement opportunities identified
+- [x] **Feasibility assessed**: Technical requirements understood
+- [x] **Enhancement priorities set**: Implementation order defined
+
+### Commit Tracking
+- Analysis initiation: `<checksum_analysis_start>`
+- Template inventory: `<checksum_template_inventory>`
+- Build pipeline analysis: `<checksum_build_analysis>`
+- Gap identification: `<checksum_gap_analysis>`
+- Phase completion: `<checksum_phase1_complete>`
+
+## Next Phase Preparation
+
+Phase 2 (Template Modification) should focus on:
+1. **Class template enhancement** with physics sections
+2. **Mathematical notation integration** using Sphinx math extensions
+3. **Function template creation** for standalone physics functions
+4. **Module template enhancement** with scientific context
+5. **Unit documentation integration** for physical quantities
+
+The analysis reveals that the current template system provides a solid foundation for enhancement, with low risk and high potential value for scientific documentation improvements.