Issue #32: Add comprehensive MkDocs documentation #48
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implements Issue #32: OpenMagnetics Documentation - Add MkDocs configuration with Material theme and mermaid support - Create documentation structure: - Getting Started (installation, quick-start, examples) - Physical Models (auto-generated from source) - Settings Reference (auto-generated from Settings.h) - Algorithm flowcharts (Core/Coil/Wire/Magnetic advisers) - API reference overview - Add extraction scripts in docs/scripts/: - extract_model_docs.py: Extracts model info from C++ headers - extract_settings.py: Extracts settings from Settings.h - generate_substack.py: Generates standalone articles - Add GitHub Actions workflow for auto-deployment to GitHub Pages - Update .gitignore to allow docs/ but ignore generated output Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add more examples similar to PyOpenMagnetics including: - Creating a core from scratch (shape, material, gapping) - Winding a coil with interleaving options - Core loss calculations with different models - Winding loss calculations (DC, skin, proximity) - Complete design adviser workflow - Buck inductor design example - Flyback transformer design example - Model comparison (reluctance, core losses) - Working with custom waveforms - Configuration settings reference - JSON import/export - Python (PyMKF) examples Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Enhanced extract_model_docs.py with DETAILED_DOCS containing rich documentation
- Added comprehensive content for all physical model categories:
- Core losses: Steinmetz, iGSE, MSE, NSE, Roshen, Albach, Barg models
- Reluctance: Classic, Zhang, Muehlethaler, Partridge, Stenglein, Balakrishnan
- Winding losses: Skin effect (Dowell, Wojda, Albach, Payne, Kutkut, Ferreira)
Proximity effect (Rossmanith, Lammeraner, Dowell, Albach, Ferreira)
- Magnetic field: Binns-Lawrenson, Dowell, Wang, Albach with fringing models
- Inductance: Reluctance-based, matrix theory, leakage inductance
- Capacitance: Koch, Massarini, Albach, Duerdoth models
- Thermal: Maniktala, Kazimierczuk, TDK, Dixon, Amidon models
- Included 45+ scientific paper references with IEEE/publication links
- Added mathematical equations in LaTeX format
- Added model selection guides and design tips
- Added usage examples and configuration settings
Total documentation: 1,200+ lines across 8 model files
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix regex backtracking vulnerability in class pattern matching - Change http to https in external references - Move GitHub workflow permissions to job level (security best practice) - Extract duplicated string literals to constants - Refactor generate_enhanced_markdown() to reduce cognitive complexity - Remove unused variable 'cat_key' - Remove unused function parameter 'cpp_type' - Remove unused assignment to 'anchor' variable
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Implements Issue #32: OpenMagnetics Documentation with comprehensive auto-generated documentation using MkDocs + Material theme.
Features Added
Scientific Content
Files Added/Modified
Test plan
🤖 Generated with Claude Code