feat(docs): use consistent ordering when generating docs#18893
feat(docs): use consistent ordering when generating docs#18893nijel merged 1 commit intoWeblateOrg:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
This PR improves determinism and contributor workflow around Weblate’s autogenerated documentation snippets by enforcing consistent section ordering, adding support for splitting list_addons output into separate snippet files, and updating contributor/admin docs accordingly (Fixes #18724).
Changes:
- Refactors
DocGeneratorCommandto merge/reorder existing autogenerated sections deterministically while preserving per-section manual “tails”. - Extends
list_addonswith--sectionsfiltering and updates tests to validate split outputs. - Splits add-ons documentation snippets into events/add-ons/parameters files and updates the docs build workflow/docs pages.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| weblate/utils/tests/test_commands.py | Adds unit tests validating deterministic merge/reorder behavior for doc generator output files. |
| weblate/utils/management/base.py | Implements marker prefix constants and new merge/reorder logic for autogenerated doc sections. |
| weblate/addons/tests.py | Adds coverage for list_addons --sections split output and verifies parameter heading presence. |
| weblate/addons/management/commands/list_addons.py | Adds --sections filtering and orders shared parameter docs consistently. |
| docs/snippets/addons-autogenerated.rst | Updates generated add-ons snippet to contain only built-in add-ons content (no events/params). |
| docs/snippets/addon-parameters-autogenerated.rst | New generated snippet for common add-on parameters. |
| docs/snippets/addon-events-autogenerated.rst | New generated snippet for add-on events. |
| docs/Makefile | Updates update-docs to generate the three add-ons snippet files separately. |
| docs/contributing/documentation.rst | Updates contributor workflow to use make -C docs update-docs and clarifies what is autogenerated. |
| docs/changes.rst | Notes the contributor documentation workflow update in the 5.17 changelog. |
| docs/admin/management.rst | Documents the new list_addons --sections option. |
| docs/admin/addons.rst | Rewires the add-ons admin doc page to include the new split snippet files and restores obsolete add-ons as manual text. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7b6e335cfd
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
- Use consistent ordering so that the content doesn't appear in random order when added. - Update contributor documentation to match the current flow. - Split add-ons docs to make it easier to generate. Fixes WeblateOrg#18724
Fixes #18724