Conversation
Plan includes: - Phase 1: Essential fixes (remove usage-old.rst, migration guide, complete templates.md TODOs, enhance contributing.md) - Phase 2: Structure improvements (glossary, concepts, diagrams) - Phase 3: Advanced content (CI/CD, best practices, troubleshooting) - Phase 4: Optional examples expansion Estimated growth: 756 -> ~1,322 lines across 4 phases Phase 1 tasks are safe to implement without conflicting with UV refactoring branch documentation changes.
The file was marked as 'mostly outdated' and its content is covered in other documentation sections (getting-started.md, preseeds.md, templates.md). No references to this file exist in the documentation TOC or other files.
Created comprehensive migration guide covering: - v1.3.1: MXENV_UV_GLOBAL removal and UV auto-detection - v1.0a7: npm → nodejs domain rename - v1.0a6: Python 3.8 dropped, minimum Python 3.9 - v1.0a4: Default venv folder change, PYTHON_BIN → PRIMARY_PYTHON - v1.0a4: MXENV_PATH removal - v1.0a1: Terminology changes, _SENTINEL → _TARGET Each change includes before/after examples and clear migration steps. Added migration.md to documentation TOC after preseeds.
Replaced TODO sections with practical examples: - Templates via mx.ini: Configuration, available built-in templates - Python-based templates: Class structure, @template decorator, MxIniBoundTemplate for mx.ini integration Added code examples showing how to create custom templates.
Added comprehensive sections: - Development Setup: Prerequisites, quick start, running tests - Code Quality: Commands for check, typecheck, format - Building Documentation: Commands for docs and link checking - Pull Request Guidelines: Before submitting checklist, commit message standards (no AI mentions), submission workflow Expanded from 17 to 103 lines with actionable guidance.
Phase 1 completed with 5 commits: - Removed obsolete usage-old.rst - Created comprehensive migration guide (128 lines) - Completed templates.md TODOs (65 lines added) - Enhanced contributing.md (87 lines added) Total impact: +168 net lines (756 -> 924 lines) All tasks completed except FAQ (deferred to avoid conflicts).
jensens
force-pushed
the
docs/improvement-plan
branch
from
3c3a74a to
a137f7c
Compare
Adds comprehensive troubleshooting guide covering UV installation, Python version mismatches, test execution, environment variables, and Makefile regeneration. Completes Phase 1 of documentation plan.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Phase 1 of documentation improvements - essential fixes and enhancements.
See
docs/DOCUMENTATION_IMPROVEMENT_PLAN.mdfor complete details.Changes
Removed
docs/source/usage-old.rst- Obsolete documentation removedAdded
docs/source/migration.md- Breaking changes guide covering versions 1.0+docs/source/getting-started.md- 6 common issues with solutionsEnhanced
docs/source/templates.md- Completed all TODOs, added Jinja2 and Python template examplesdocs/source/contributing.md- Added development setup and PR guidelinesdocs/source/index.md- Updated TOCImpact
Phase 1 Success Criteria
All Phase 1 tasks completed and ready for review.