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

plans/completed/docstring-audit-enhancement/0-Overview.md

@@ -0,0 +1,274 @@
+# SolarWindPy Docstring Audit and Enhancement Plan
+
+## **Executive Summary**
+
+**OBJECTIVE**: Conservative docstring audit and format standardization of all 53 Python modules in SolarWindPy package for strict NumPy convention compliance.
+
+**SCOPE**: Format standardization and consistency enhancement of existing docstrings across core/, fitfunctions/, plotting/, solar_activity/, instabilities/, and tools/ packages. Focus on compliance over content expansion.
+
+**QUALITY TARGET**: 100% NumPy docstring convention compliance through format standardization and minimal content enhancement.
+
+## **Business Case and Value Proposition**
+
+### **Critical Documentation Issues**
+- **Format Inconsistencies**: Mixed docstring styles (Google/informal vs NumPy format)
+- **Parameter Documentation**: Inconsistent type notation and descriptions
+- **Missing Basic Docstrings**: Some methods and functions completely lack documentation
+- **LaTeX Formatting**: Inconsistent mathematical notation formatting
+- **Return Documentation**: Missing or incomplete Returns sections
+
+### **Benefits of Standardization**
+- **Format Consistency**: Uniform NumPy docstring format across entire codebase
+- **Developer Experience**: Standardized documentation improves maintainability
+- **Tool Compatibility**: Better pydocstyle and Sphinx integration
+- **Code Quality**: Consistent formatting standards improve readability
+- **IDE Integration**: Enhanced autocomplete through standardized parameter documentation
+
+## **Scope Analysis**
+
+### **Module Inventory (53 Python files)**
+
+#### **Core Physics Modules (9 files)**
+- `core/__init__.py` - Package entry point
+- `core/base.py` - Base class with logging and utilities  
+- `core/plasma.py` - Main Plasma container class
+- `core/ions.py` - Ion species handling
+- `core/spacecraft.py` - Spacecraft trajectory data
+- `core/vector.py` - Vector mathematical operations
+- `core/tensor.py` - Tensor mathematical operations  
+- `core/units_constants.py` - Physical constants and conversions
+- `core/alfvenic_turbulence.py` - Alfven wave turbulence calculations
+
+#### **Fitfunctions Mathematical Modules (10 files)**
+- `fitfunctions/__init__.py` - Package entry point
+- `fitfunctions/core.py` - Abstract FitFunction base class
+- `fitfunctions/gaussians.py` - Gaussian distribution fits
+- `fitfunctions/exponentials.py` - Exponential function fits
+- `fitfunctions/lines.py` - Linear regression fits
+- `fitfunctions/power_laws.py` - Power law function fits
+- `fitfunctions/moyal.py` - Moyal distribution fits  
+- `fitfunctions/trend_fits.py` - Trend analysis fits
+- `fitfunctions/plots.py` - Fit visualization tools
+- `fitfunctions/tex_info.py` - LaTeX formatting utilities
+
+#### **Plotting Visualization Modules (18 files)**
+- `plotting/__init__.py` - Package entry point
+- `plotting/base.py` - Base plotting utilities
+- `plotting/agg_plot.py` - Aggregated plot utilities
+- `plotting/histograms.py` - Histogram plotting (deprecated, use hist1d/hist2d)
+- `plotting/hist1d.py` - 1D histogram plots
+- `plotting/hist2d.py` - 2D histogram plots
+- `plotting/scatter.py` - Scatter plot utilities
+- `plotting/spiral.py` - Spiral mesh calculations
+- `plotting/orbits.py` - Orbital trajectory plots
+- `plotting/tools.py` - General plotting tools
+- `plotting/select_data_from_figure.py` - Interactive data selection
+- `plotting/labels/__init__.py` - Labels package entry point
+- `plotting/labels/base.py` - Base label formatting
+- `plotting/labels/special.py` - Special scientific labels
+- `plotting/labels/chemistry.py` - Chemical species labels
+- `plotting/labels/composition.py` - Composition ratio labels
+- `plotting/labels/datetime.py` - Time formatting labels
+- `plotting/labels/elemental_abundance.py` - Element abundance labels
+
+#### **Solar Activity Modules (8 files)**
+- `solar_activity/__init__.py` - Package entry point
+- `solar_activity/base.py` - Base solar activity classes
+- `solar_activity/plots.py` - Solar activity plotting
+- `solar_activity/lisird/__init__.py` - LISIRD package entry point
+- `solar_activity/lisird/lisird.py` - LISIRD data interface
+- `solar_activity/lisird/extrema_calculator.py` - Solar extrema calculations
+- `solar_activity/sunspot_number/__init__.py` - Sunspot package entry point
+- `solar_activity/sunspot_number/sidc.py` - SIDC sunspot data interface
+
+#### **Instabilities Physics Modules (2 files)**
+- `instabilities/__init__.py` - Package entry point  
+- `instabilities/beta_ani.py` - Beta-anisotropy instability calculations
+- `instabilities/verscharen2016.py` - Verscharen 2016 instability model
+
+#### **Tools and Utilities (6 files)**
+- `tools/__init__.py` - Package entry point
+- `scripts/__init__.py` - Scripts package entry point  
+- `plans/__init__.py` - Plans package entry point
+- `plans/issues_from_plans.py` - Issue generation utility
+- `__init__.py` - Main package entry point
+- Additional utility scripts
+
+## **Implementation Strategy**
+
+### **Quality Standards**
+
+#### **NumPy Docstring Convention Requirements**
+```python
+def function(param1, param2=None):
+    """Short one-line summary.
+    
+    Longer description with more details about the function's 
+    purpose and behavior.
+    
+    Parameters
+    ----------
+    param1 : type
+        Description of param1.
+    param2 : type, optional
+        Description of param2. Default is None.
+        
+    Returns
+    -------
+    type
+        Description of return value.
+        
+    Raises
+    ------
+    ValueError
+        When invalid input is provided.
+        
+    Examples
+    --------
+    >>> result = function(1, 2)
+    >>> print(result)
+    3
+    
+    Notes
+    -----
+    Additional technical notes about the implementation.
+    
+    References
+    ----------
+    .. [1] Author, "Title", Journal, Year.
+    """
+```
+
+#### **Scientific Documentation Requirements**
+- **Mathematical Notation**: Proper LaTeX formatting in docstrings
+- **Physical Units**: Clear unit specifications for all quantities
+- **Literature References**: Proper citations for physics algorithms
+- **Parameter Validation**: Clear documentation of expected ranges/values
+
+#### **Coverage Requirements**
+- **100% Public API**: All public classes, methods, functions documented
+- **Module-Level**: Comprehensive module docstrings with usage examples
+- **Property Documentation**: All properties with getter/setter documentation
+- **Internal Methods**: Key internal methods documented for maintainability
+
+### **Validation Framework**
+
+#### **Automated Validation Tools**
+- **pydocstyle**: NumPy convention compliance checking
+- **Sphinx Integration**: Documentation build validation  
+- **Custom Validators**: Physics-specific validation (units, equations)
+- **Example Testing**: Docstring example code validation
+
+#### **Manual Review Checklist**
+- [ ] NumPy format compliance
+- [ ] Complete parameter documentation
+- [ ] Proper return value documentation
+- [ ] Exception documentation
+- [ ] Usage examples included
+- [ ] Mathematical notation correct
+- [ ] Physical units specified
+- [ ] Literature references included
+
+## **Phase Structure**
+
+### **Phase 1: Infrastructure Setup and Validation Tools** (Est. 3 hours)
+- Set up pydocstyle configuration for NumPy convention
+- Create baseline documentation coverage analysis
+- Configure validation scripts for format compliance
+- Establish Sphinx integration for consistent builds
+
+### **Phase 2: Core Physics Modules Format Standardization** (Est. 8 hours)  
+**Target: 9 core module files**
+- Convert existing docstrings to strict NumPy format
+- Standardize parameter type notation (e.g., array_like)
+- Add missing Returns sections where functions return values
+- Standardize existing LaTeX equation formatting
+
+### **Phase 3: Fitfunctions Mathematical Modules Format Standardization** (Est. 7 hours)
+**Target: 10 fitfunction module files**  
+- Convert docstrings to NumPy format compliance
+- Standardize mathematical notation formatting
+- Ensure consistent parameter documentation format
+- Add basic docstrings where completely missing
+
+### **Phase 4: Plotting Visualization Modules Format Standardization** (Est. 10 hours)
+**Target: 18 plotting module files**
+- Convert mixed docstring styles to NumPy format
+- Standardize parameter documentation for plotting functions
+- Add basic module-level docstrings where missing
+- Ensure consistent Returns section formatting
+
+### **Phase 5: Specialized Modules Format Standardization** (Est. 6 hours)
+**Target: 16 specialized module files (solar_activity, instabilities, tools, etc.)**
+- Convert existing docstrings to NumPy format
+- Add basic docstrings for undocumented functions
+- Standardize parameter and return documentation
+- Ensure consistent module-level documentation
+
+### **Phase 6: Validation and Integration** (Est. 3 hours)
+- Run comprehensive pydocstyle validation
+- Fix remaining format compliance issues
+- Validate Sphinx documentation builds
+- Ensure consistency across all modules
+
+## **Success Criteria**
+
+### **Primary Success Metrics**
+- **100% NumPy Convention Compliance**: All docstrings pass pydocstyle validation
+- **Complete API Coverage**: Every public method, class, and function documented
+- **Enhanced Sphinx Build**: Comprehensive auto-generated documentation
+- **Example Code Validation**: All docstring examples execute successfully
+
+### **Quality Assurance Metrics**
+- **Zero pydocstyle Violations**: Clean docstring format compliance
+- **Comprehensive Parameter Documentation**: All parameters with types and descriptions
+- **Mathematical Notation**: Proper LaTeX formatting in scientific modules
+- **Usage Examples**: Practical examples for key functionality
+
+## **Timeline and Resource Allocation**
+
+### **Total Estimated Duration: 37 hours**
+- **Phase 1**: 3 hours (Infrastructure)
+- **Phase 2**: 8 hours (Core modules - 9 files)
+- **Phase 3**: 7 hours (Fitfunctions - 10 files)  
+- **Phase 4**: 10 hours (Plotting - 18 files)
+- **Phase 5**: 6 hours (Specialized - 16 files)
+- **Phase 6**: 3 hours (Validation)
+
+### **Resource Requirements**
+- **Technical Expertise**: Python documentation standards, NumPy docstring conventions
+- **Basic Domain Knowledge**: Understanding of existing code functionality
+- **Tools**: pydocstyle, Sphinx, basic LaTeX formatting knowledge
+
+## **Risk Mitigation**
+
+### **Potential Challenges**
+- **Format Conversion**: Converting mixed docstring styles to NumPy format
+- **Legacy Code**: Inconsistent existing documentation styles
+- **Format Compliance**: Ensuring strict pydocstyle compliance
+- **Large Scope**: 53 modules requiring systematic standardization
+
+### **Mitigation Strategies**
+- **Incremental Validation**: Phase-by-phase pydocstyle checking
+- **Conservative Approach**: Focus on format over content to avoid errors
+- **Template Standardization**: Consistent NumPy format patterns
+- **Automated Tooling**: pydocstyle validation pipeline
+
+## **Long-term Benefits**
+
+### **Maintainability Improvements**
+- **Developer Onboarding**: Clear API documentation for new contributors
+- **Code Comprehension**: Enhanced understanding of complex physics calculations
+- **Debugging Support**: Better documentation aids in troubleshooting
+
+### **User Experience Enhancements**  
+- **Auto-generated Documentation**: Professional-quality API reference
+- **IDE Integration**: Enhanced autocomplete and help systems
+- **Scientific Integrity**: Proper mathematical notation and citations
+
+### **Quality Assurance**
+- **Consistency Standards**: Uniform documentation across entire codebase
+- **Validation Pipeline**: Automated compliance checking in CI/CD
+- **Future-proofing**: Established patterns for new module development
+
+This conservative docstring audit and format standardization plan will achieve 100% NumPy docstring convention compliance across SolarWindPy, providing consistent documentation formatting while maintaining scientific accuracy through minimal content changes.

plans/completed/docstring-audit-enhancement/1-Infrastructure-Setup-and-Validation-Tools.md

@@ -0,0 +1,206 @@
+# Phase 1: Infrastructure Setup and Validation Tools
+
+## **Objective**
+Establish docstring format validation infrastructure and baseline coverage analysis for NumPy convention compliance across the SolarWindPy codebase.
+
+## **Scope**
+Set up pydocstyle validation and baseline analysis tools to ensure strict NumPy docstring format compliance across all 53 Python modules.
+
+## **Implementation Tasks**
+
+### **Task 1: Docstring Validation Tool Configuration** (1 hour)
+
+#### **pydocstyle Configuration Setup**
+```ini
+# .pydocstyle configuration file
+[pydocstyle]
+convention = numpy
+match = (?!test_).*\.py
+add-ignore = D100,D104,D105
+add-source = solarwindpy/
+```
+
+#### **Configuration Requirements**
+- **Convention**: Strict NumPy docstring format
+- **Scope**: All solarwindpy/ modules excluding test files
+- **Ignored Checks**: Module-level docstrings for __init__.py files (selective)
+- **Source Path**: Target solarwindpy package directory
+
+#### **Integration Points**
+- Add pydocstyle to requirements-dev.txt
+- Configure pre-commit hook for docstring validation
+- Set up CI/CD pipeline integration for automated checking
+
+### **Task 2: Format Compliance Baseline Analysis** (1 hour)
+
+#### **Format Compliance Analysis Script**
+```python
+#!/usr/bin/env python
+"""Docstring format compliance analysis for SolarWindPy modules."""
+
+import ast
+import os
+from pathlib import Path
+
+class DocstringFormatAnalyzer(ast.NodeVisitor):
+    """Analyze docstring format compliance in Python modules."""
+    
+    def __init__(self):
+        self.stats = {
+            'total_docstrings': 0,
+            'numpy_format': 0,
+            'google_format': 0,
+            'informal_format': 0,
+            'missing_docstrings': 0,
+        }
+        self.format_issues = []
+```
+
+#### **Analysis Targets**
+- **Format Detection**: Identify NumPy vs Google vs informal docstring styles
+- **Missing Docstrings**: Functions/methods completely lacking documentation
+- **Parameter Format**: Inconsistent parameter documentation styles
+- **Returns Section**: Missing or improperly formatted returns documentation
+
+#### **Baseline Metrics Collection**
+- Current format compliance percentage by module
+- Identification of mixed docstring styles
+- Priority ranking for standardization based on format inconsistencies
+
+### **Task 3: NumPy Format Validation Framework** (0.5 hours)
+
+#### **Format Compliance Rules**
+```python
+class NumPyFormatValidator:
+    """Validate NumPy docstring format compliance."""
+    
+    REQUIRED_SECTIONS = {
+        'functions': ['Parameters', 'Returns'],
+        'methods': ['Parameters', 'Returns'],  
+        'classes': ['Parameters'],
+        'properties': ['Returns'],
+    }
+    
+    FORMAT_REQUIREMENTS = {
+        'parameter_format': True,  # param : type format
+        'section_headers': True,   # Proper section formatting
+        'consistent_style': True,  # NumPy format throughout
+    }
+```
+
+#### **Format Standardization Focus**
+- **Parameter Format**: Consistent `param : type` notation
+- **Section Headers**: Proper underline formatting for NumPy sections
+- **Type Documentation**: Standardized type annotations
+- **Returns Format**: Consistent return value documentation
+
+#### **Validation Workflow**
+1. **Format Compliance**: NumPy convention structure validation
+2. **Section Presence**: Required sections existence check
+3. **Style Consistency**: Uniform formatting across modules
+4. **pydocstyle Integration**: Automated compliance checking
+
+### **Task 4: Sphinx Integration Setup** (0.5 hours)
+
+#### **Sphinx Configuration Updates**
+```python
+# docs/conf.py enhancements
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',  # NumPy/Google style docstrings
+    'sphinx.ext.viewcode',
+    'sphinx.ext.mathjax',   # LaTeX math rendering
+    'sphinx.ext.doctest',   # Docstring example testing
+    'numpydoc',             # Enhanced NumPy docstring support
+]
+
+napoleon_config = {
+    'napoleon_google_docstring': False,
+    'napoleon_numpy_docstring': True,
+    'napoleon_include_init_with_doc': True,
+    'napoleon_include_private_with_doc': False,
+    'napoleon_include_special_with_doc': True,
+    'napoleon_use_admonition_for_examples': False,
+    'napoleon_use_admonition_for_notes': False,
+    'napoleon_use_admonition_for_references': False,
+    'napoleon_use_ivar': False,
+    'napoleon_use_param': True,
+    'napoleon_use_rtype': True,
+}
+```
+
+#### **Documentation Build Configuration**
+- **NumPy Style Support**: Napoleon extension for NumPy format
+- **Consistent Rendering**: Standardized docstring presentation
+- **Format Validation**: Sphinx build warnings for format issues
+- **API Reference**: Clean automated documentation generation
+
+## **Validation and Testing Criteria**
+
+### **Tool Validation Requirements**
+- [ ] pydocstyle runs successfully on entire codebase
+- [ ] Coverage analysis script executes without errors
+- [ ] Custom validation rules detect compliance issues correctly
+- [ ] Sphinx builds enhanced documentation successfully
+
+### **Baseline Format Compliance Metrics**
+- [ ] **Format Distribution**: Percentage of NumPy vs other formats per module
+- [ ] **Priority List**: Modules with highest format inconsistency
+- [ ] **Compliance Report**: pydocstyle violation summary
+- [ ] **Missing Documentation**: Functions completely lacking docstrings
+
+### **Infrastructure Quality Checks**
+- [ ] **pydocstyle Integration**: Automated format validation
+- [ ] **Pre-commit Hooks**: Format checking in developer workflow
+- [ ] **Sphinx Build**: Consistent documentation generation
+- [ ] **Format Validation**: NumPy convention compliance checking
+
+## **Deliverables**
+
+### **Configuration Files**
+- `.pydocstyle` - NumPy convention configuration
+- `scripts/format_analysis.py` - Format compliance analysis tool
+- `scripts/validate_formats.py` - NumPy format validation framework
+- Updated `docs/conf.py` - NumPy-focused Sphinx configuration
+
+### **Baseline Reports**
+- **Format Report**: Current docstring format distribution by module
+- **Compliance Report**: pydocstyle violations summary
+- **Priority Matrix**: Standardization priority by format inconsistency
+- **Missing Documentation**: Functions requiring basic docstrings
+
+### **Validation Pipeline**
+- **Pre-commit Integration**: Developer workflow validation
+- **CI/CD Checks**: Automated pull request validation  
+- **Documentation Build**: Enhanced API reference generation
+- **Example Testing**: Docstring code validation framework
+
+## **Success Criteria**
+
+### **Primary Infrastructure Goals**
+- **Format Validation**: pydocstyle NumPy convention checking operational
+- **Baseline Analysis**: Current format compliance status established
+- **Standardization Pipeline**: Automated format validation framework
+- **Sphinx Integration**: NumPy-focused documentation build capability
+
+### **Quality Assurance Standards**
+- **NumPy Compliance**: Validation rules enforce strict format adherence
+- **Format Consistency**: Uniform docstring style across all modules
+- **pydocstyle Integration**: Zero violations target for format compliance
+- **Developer Integration**: Seamless format checking in development workflow
+
+## **Next Phase Prerequisites**
+
+### **Infrastructure Readiness**
+- Format validation tools configured and operational
+- Baseline format compliance metrics documented and analyzed
+- Priority standardization list established and reviewed
+- Documentation build pipeline tested for NumPy format support
+
+### **Quality Framework**
+- NumPy docstring format enforcement active
+- Format consistency standards defined and implemented
+- pydocstyle validation framework operational
+- Automated format checking integrated into development workflow
+
+This infrastructure foundation enables systematic, automated, and consistent docstring format standardization across the entire SolarWindPy codebase while maintaining existing scientific content accuracy.