Automatic documentation generation

[gersona]

• fixes Automate documentation updates (add-ons, machinery, checks) #17761

The approach is to use markers in the target document in order to combine automatically generated content (within the markers) and custom/handwritten content.
This has is drawbacks, but it allows to keep a minimal number of files to maintain, and reduces mix of concern between documentation code and actual logic code.

[gersona]

@nijel, can you share your thoughts on this approach for automating documentation generation ?

[codecov]

Codecov Report

❌ Patch coverage is 83.51648% with 15 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.00%. Comparing base (7e2c4f8) to head (dc20e72).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
weblate/addons/management/commands/list_addons.py	72.22%	12 Missing and 3 partials ⚠️

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nijel]

I think it's a reasonable approach. See a few comments I've made on the implementation. I will also trigger copilot review to comment on this.

[Copilot]

Pull request overview

Adds scaffolding for automatic documentation generation by introducing version metadata markers for add-ons and updating the list_addons management command to emit/insert auto-generated RST blocks.

Changes:

• Introduced RST “versionadded/versionchanged” metadata helper classes and attached version metadata to various add-ons.
• Extended ./manage.py list_addons to write generated docs either to stdout or into a file section delimited by markers.
• Added human-readable descriptions for add-on events to improve generated documentation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
weblate/utils/docs.py	Adds RST version metadata helpers for embedding versionadded/versionchanged directives.
weblate/addons/base.py	Introduces doc_versions on add-on base class for documentation metadata.
weblate/addons/webhooks.py	Adds doc_versions metadata to webhook add-ons.
weblate/addons/gettext.py	Updates add-on description formatting and adds versionchanged metadata.
weblate/addons/generate.py	Adds versionadded metadata for locale-generation add-ons.
weblate/addons/fedora_messaging.py	Adds versionadded metadata for Fedora Messaging add-on.
weblate/addons/cleanup.py	Adds versionadded metadata for Remove Blank add-on.
weblate/addons/cdn.py	Adds versionadded metadata for CDNJS add-on.
weblate/addons/events.py	Adds event description strings used in generated docs.
weblate/addons/management/commands/list_addons.py	Adds marker-based insertion into an output file and restructures doc generation output.

[Copilot]

Pull request overview

Copilot reviewed 51 out of 51 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (7)

weblate/utils/management/base.py:1

• sections is a mutable ClassVar, so it is shared across all instances and subclasses. This can leak sections between different call_command(...) invocations (and even across different commands inheriting DocGeneratorCommand), producing incorrect docs output. Make sections an instance attribute (initialize self.sections = [] in __init__ or at the start of handle) and remove the ClassVar.
  weblate/utils/management/base.py:1
• sections is a mutable ClassVar, so it is shared across all instances and subclasses. This can leak sections between different call_command(...) invocations (and even across different commands inheriting DocGeneratorCommand), producing incorrect docs output. Make sections an instance attribute (initialize self.sections = [] in __init__ or at the start of handle) and remove the ClassVar.
  weblate/utils/management/base.py:1
• If both markers exist multiple times, or if end_marker appears before start_marker, this will splice the wrong range (possibly deleting unrelated content). Consider locating end_marker starting from start_index + 1 (e.g., lines.index(end_marker, start_index + 1)) and, if the ordering is invalid, either raise an error or fall back to appending at EOF.
  weblate/utils/docs.py:1
• The docstring references get_versions_output(), but the implemented API is get_versions_rst_lines(). Update the docstring to match the actual method name to avoid confusing API consumers.
  weblate/utils/docs.py:1
• body can contain embedded newlines, but downstream code treats each list element as a single RST line (later doing \"\\n\".join(...)). Returning multi-line strings makes line-based insertion harder to reason about and can create subtle formatting issues. Prefer splitting into individual lines (e.g., indent each line and extend them) so get_versions_rst_lines() always returns a true list[str] of lines.
  weblate/checks/management/commands/list_checks.py:1
• This stores a trailing newline inside a single 'line' element. Because output is later assembled with \"\\n\".join(lines), embedding newline characters inside one element can lead to inconsistent spacing and makes marker replacement logic harder to keep stable. Use separate list elements instead (anchor line without \\n, followed by an explicit empty string when you need a blank line).
  weblate/checks/management/commands/list_checks.py:1
• enable_flags is annotated as list[str] but is assigned a set literal. This is a concrete type mismatch and will trip static type checking. Either change the annotation to set[str] or build a list explicitly (and preserve ordering expectations if needed).

[nijel]

@gersona Can you check copilot comments? At least the type annotations ones seem legit to me.