Split developer guide into separate chapters + other tweaks to docs #1059
Conversation
mdBook automatically converts these to `index.html`. By doing it this way, the main file will be displayed if manually navigating through the repo on GitHub.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1059 +/- ##
=======================================
Coverage 82.09% 82.09%
=======================================
Files 53 53
Lines 7310 7310
Branches 7310 7310
=======================================
Hits 6001 6001
Misses 1019 1019
Partials 290 290 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR reorganizes the developer documentation into separate chapters and makes various documentation improvements. The main developer guide has been split into three focused chapters covering setup, coding, and documentation development. Additionally, main documentation files have been renamed to README.md for improved navigation on GitHub, and unicode apostrophes have been replaced with standard ASCII apostrophes throughout.
- Restructured developer guide from a single file into separate chapters
- Renamed main documentation files to README.md for better GitHub browsing
- Fixed unicode apostrophes to ASCII apostrophes in model documentation
- Enhanced justfile coverage command to accept arguments
Reviewed changes
Copilot reviewed 13 out of 16 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| justfile | Added argument passing capability to coverage command |
| docs/model/investment.md | Replaced unicode apostrophes with ASCII apostrophes and updated links to README.md |
| docs/model/dispatch_optimisation.md | Replaced unicode apostrophes with ASCII apostrophes |
| docs/model/README.md | Renamed from model_description.md for better GitHub navigation |
| docs/file_formats/README.md | New file introducing file formats section |
| docs/developer_guide/setup.md | New chapter covering development environment setup |
| docs/developer_guide/docs.md | New chapter covering documentation development |
| docs/developer_guide/coding.md | New chapter covering building and developing MUSE2 |
| docs/developer_guide/README.md | New intro file for developer guide with link to API docs |
| docs/developer_guide.md | Deleted - content split into separate chapter files |
| docs/api/muse2/README.md | New placeholder file for API documentation |
| docs/SUMMARY.md | Updated to reflect new file structure and chapter organization |
| docs/README.md | Updated links to point to new README.md files |
| CONTRIBUTING.md | Updated developer guide link |
| CITATION.cff | Replaced unicode apostrophe with ASCII apostrophe |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Description
I was planning on making a start on a coding style document for humans and robots (following discussion on #1057), but figured it probably made sense to reorganise the developer docs a bit first. Presently all developer documentation lives in
docs/developer_guide.md, but it's now a fairly long document covering a number of different topics (toolchain installation, pre-commit, building docs etc.) which probably deserve their own "chapters" (in mdbook-speak). So this is what I've done.I made some small corrections/tweaks to the developer docs while I was at it, but nothing substantial has changed.
I also made some other docs-related tweaks:
justfiledocs/and subfolders toREADME.mdso they can also be navigated directly from github.comType of change
Key checklist
$ cargo test$ cargo docFurther checks