documentation updates

Author: wdm0006

docs/AUDIT_REPORT.md

@@ -0,0 +1,171 @@
+# Git-Pandas Documentation Audit Report
+
+## Executive Summary
+
+The documentation audit has been completed for git-pandas v2.5.0. Overall, the documentation is comprehensive and well-structured, but several inconsistencies and outdated information were identified and corrected.
+
+## Issues Found and Corrected
+
+### ✅ FIXED - Critical Issues
+
+1. **Version Information Inconsistency**
+   - **Issue**: conf.py showed version "2.2.1" while current version is "2.5.0"
+   - **Fix**: Updated conf.py to reflect correct version "2.5.0"
+   - **Files**: `docs/source/conf.py`
+
+2. **Missing Performance Documentation**
+   - **Issue**: performance.rst was created but not included in main table of contents
+   - **Fix**: Added performance.rst to index.rst toctree
+   - **Files**: `docs/source/index.rst`
+
+3. **Incomplete Bus Factor Documentation**
+   - **Issue**: Bus factor docs didn't mention file-wise analysis option
+   - **Fix**: Updated repository.rst and project.rst to show 'file' option
+   - **Files**: `docs/source/repository.rst`, `docs/source/project.rst`
+
+### ✅ FIXED - Content Updates
+
+4. **Cache System Documentation**
+   - **Issue**: Overview didn't mention cache management features
+   - **Fix**: Added cache management and statistics to feature list
+   - **Files**: `docs/source/cache.rst`
+
+5. **Use Cases Missing New Features**
+   - **Issue**: No examples of file-wise bus factor or cache management
+   - **Fix**: Added comprehensive examples for v2.5.0 features
+   - **Files**: `docs/source/usecases.rst`
+
+6. **Contributors Page Outdated**
+   - **Issue**: Didn't reflect recently completed features
+   - **Fix**: Added "Recently Completed (v2.5.0)" section
+   - **Files**: `docs/source/contributors.rst`
+
+## Documentation Quality Assessment
+
+### ✅ EXCELLENT - Well Documented Areas
+
+1. **Cache System** (`cache.rst`)
+   - Comprehensive coverage of all cache backends
+   - Clear examples for each cache type
+   - Good coverage of cache management features
+   - Proper API reference with autodoc
+
+2. **Remote Operations** (`remote_operations.rst`)
+   - Detailed documentation of safe_fetch_remote
+   - Complete coverage of cache warming features
+   - Good examples and error handling documentation
+   - Comprehensive return value documentation
+
+3. **Performance Guide** (`performance.rst`)
+   - Thorough performance optimization strategies
+   - Benchmark data and real-world examples
+   - Best practices and anti-patterns
+   - Memory management guidance
+
+### ✅ GOOD - Generally Well Documented
+
+4. **Repository API** (`repository.rst`)
+   - Good coverage of core methods
+   - Clear parameter documentation
+   - Could benefit from more advanced examples
+
+5. **Project Directory** (`project.rst`)
+   - Adequate coverage of multi-repository features
+   - Good examples of different initialization methods
+
+6. **Use Cases** (`usecases.rst`)
+   - Good practical examples
+   - Now includes v2.5.0 features
+   - Could use more visualization examples
+
+### ✅ ADEQUATE - Basic Documentation
+
+7. **Index Page** (`index.rst`)
+   - Clear quick start examples
+   - Good feature overview
+   - Proper navigation structure
+
+8. **Contributors Guide** (`contributors.rst`)
+   - Standard contribution guidelines
+   - Now reflects current development status
+
+## Remaining Recommendations
+
+### High Priority
+
+1. **README.md Synchronization**
+   - Update Python version requirements (currently claims 2.7+ support)
+   - Add examples of new v2.5.0 features
+   - Update installation instructions for optional dependencies
+
+2. **API Documentation Verification**
+   - Ensure all public methods have proper docstrings
+   - Verify autodoc is picking up all new methods
+   - Check that method signatures in docs match implementation
+
+### Medium Priority
+
+3. **Cross-Reference Verification**
+   - Verify all internal links work correctly
+   - Check that all referenced examples exist
+   - Ensure consistent terminology across documents
+
+4. **Example Code Testing**
+   - Systematically test all code examples in documentation
+   - Add automated testing for documentation examples
+   - Ensure examples use realistic file paths and parameters
+
+### Low Priority
+
+5. **Enhancement Opportunities**
+   - Add more visualization examples using matplotlib/seaborn
+   - Include performance benchmarks in appropriate sections
+   - Add troubleshooting section for common issues
+
+## Testing Performed
+
+### ✅ Verified Working
+- Basic imports work correctly
+- Cache management methods exist and are callable
+- New features are accessible through public APIs
+- Documentation structure builds correctly
+
+### Manual Verification Needed
+- All code examples execute without errors
+- External links are valid and accessible
+- Cross-references resolve correctly
+
+## Files Modified in This Audit
+
+1. `docs/source/conf.py` - Version update to 2.5.0
+2. `docs/source/index.rst` - Added performance.rst to toctree
+3. `docs/source/repository.rst` - Updated bus_factor documentation
+4. `docs/source/project.rst` - Updated bus_factor options
+5. `docs/source/cache.rst` - Enhanced feature overview
+6. `docs/source/usecases.rst` - Added v2.5.0 feature examples
+7. `docs/source/contributors.rst` - Added recently completed features section
+
+## Overall Assessment
+
+**Grade: B+ (Good with room for improvement)**
+
+The documentation is comprehensive and covers all major features well. The recent additions for v2.5.0 are well-documented, particularly the cache management and remote operations features. The main areas for improvement are:
+
+1. Synchronizing README.md with current documentation
+2. Ensuring all code examples are tested and working
+3. Verifying cross-references and links
+
+The documentation successfully serves its purpose of helping users understand and use git-pandas effectively, with clear examples and comprehensive API coverage.
+
+## Next Steps
+
+1. **Immediate**: Update README.md to match documentation
+2. **Short-term**: Test all documentation examples
+3. **Medium-term**: Add automated testing for documentation examples
+4. **Long-term**: Consider adding more advanced use case examples
+
+---
+
+*Audit completed: January 2025*
+*Documentation version: 2.5.0*
+*Status: Ready for release with minor README updates needed*

docs/source/cache.rst

@@ -8,11 +8,12 @@ Overview
 
 The caching system provides:
 * In-memory caching for temporary results
-* Redis-based caching for persistent storage
-* Configurable cache durations
-* Automatic cache invalidation
+* Disk-based caching for persistent storage across sessions
+* Redis-based caching for distributed storage
+* Cache management and invalidation methods
 * Decorator-based caching for expensive operations
 * **Cache timestamp tracking** - know when cache entries were populated
+* **Cache statistics and monitoring** - track cache performance and usage
 
 Available Cache Backends
 ------------------------

docs/source/conf.py

@@ -82,9 +82,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "2.2.1"
+version = "2.5.0"
 # The full version, including alpha/beta/rc tags.
-release = "2.2.1"
+release = "2.5.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/contributors.rst

@@ -76,14 +76,23 @@ High Priority
 * Enhance documentation with more examples and visualizations
 * Streamline documentation deployment
 
+Recently Completed (v2.5.0)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* ✅ File-wise bus factor analysis (completed)
+* ✅ Cache management methods (invalidate_cache, get_cache_stats)
+* ✅ Performance documentation and optimization guide
+* ✅ Remote operations (safe_fetch_remote, warm_cache, bulk operations)
+* ✅ Enhanced caching system with timestamps and metadata
+
 Feature Ideas
 ~~~~~~~~~~~~~
 
-* File-level history tracking
 * Cross-branch analytics
 * Enhanced verbose logging
-* Hierarchical bus factor analysis
 * Language analytics and insights
+* Code complexity metrics
+* Contributor network analysis
 
 Development Setup
 -----------------

docs/source/index.rst

@@ -112,6 +112,7 @@ For detailed information about the components and their usage, see:
    project
    cache
    remote_operations
+   performance
    usecases
    contributors
 

docs/source/project.rst

@@ -103,7 +103,7 @@ Core Analysis
 
     # Bus factor analysis across repositories
     project.bus_factor(
-        by="repository",     # How to group results
+        by="repository",     # How to group results ('projectd', 'repository', or 'file')
         ignore_globs=None,
         include_globs=None
     )

docs/source/repository.rst

@@ -88,7 +88,7 @@ Core Analysis
 
     # Bus factor analysis
     repo.bus_factor(
-        by="repository",     # How to group results
+        by="repository",     # How to group results ('repository' or 'file')
         ignore_globs=None,
         include_globs=None
     )

docs/source/usecases.rst

@@ -114,6 +114,9 @@ Analyze project sustainability:
     # Calculate bus factor for repository
     bus_factor = repo.bus_factor()
     
+    # Calculate file-wise bus factor (new in v2.5.0)
+    file_bus_factor = repo.bus_factor(by='file')
+    
     # Get detailed blame information
     blame_df = repo.blame(by='file')  # Get file-level blame details
     
@@ -131,13 +134,17 @@ Optimize performance with caching:
 .. code-block:: python
 
     from gitpandas import Repository
-    from gitpandas.cache import EphemeralCache, RedisDFCache
+    from gitpandas.cache import EphemeralCache, DiskCache, RedisDFCache
     
     # Use in-memory caching
-    cache = EphemeralCache()
+    cache = EphemeralCache(max_keys=1000)
     repo = Repository('/path/to/repo', cache_backend=cache)
     
-    # Or use Redis for persistent caching
+    # Use persistent disk caching (new in v2.5.0)
+    disk_cache = DiskCache('/tmp/gitpandas_cache.gz', max_keys=500)
+    repo = Repository('/path/to/repo', cache_backend=disk_cache)
+    
+    # Or use Redis for distributed caching
     redis_cache = RedisDFCache(
         host='localhost',
         port=6379,
@@ -146,6 +153,27 @@ Optimize performance with caching:
     )
     repo = Repository('/path/to/repo', cache_backend=redis_cache)
 
+Cache Management (New in v2.5.0)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Manage cache performance and contents:
+
+.. code-block:: python
+
+    # Get cache statistics
+    stats = repo.get_cache_stats()
+    print(f"Cache usage: {stats['global_cache_stats']['cache_usage_percent']:.1f}%")
+    
+    # Invalidate specific cache entries
+    repo.invalidate_cache(keys=['commit_history'])
+    
+    # Clear all cache for this repository
+    repo.invalidate_cache()
+    
+    # Warm cache for better performance
+    result = repo.warm_cache(methods=['commit_history', 'blame'], limit=100)
+    print(f"Created {result['cache_entries_created']} cache entries")
+
 Visualization Examples
 ----------------------