feat(docs): use consistent ordering when generating docs

docs/Makefile

@@ -43,7 +43,9 @@ update-openapi:
 	@WEBLATE_HIDE_VERSION=1 uv run --no-sync ../manage.py spectacular --skip-checks --fail-on-warn --validate > specs/openapi.yaml
 
 update-docs:
-	@uv run --no-sync ../manage.py list_addons -o snippets/addons-autogenerated.rst
+	@uv run --no-sync ../manage.py list_addons --sections events -o snippets/addon-events-autogenerated.rst
+	@uv run --no-sync ../manage.py list_addons --sections addons -o snippets/addons-autogenerated.rst
+	@uv run --no-sync ../manage.py list_addons --sections parameters -o snippets/addon-parameters-autogenerated.rst
 	@uv run --no-sync ../manage.py list_machinery -o snippets/machines-autogenerated.rst
 	@uv run --no-sync ../manage.py list_file_format_params > snippets/file-format-parameters.rst
 	@uv run --no-sync ../manage.py list_permissions --sections perms > snippets/permissions.rst

docs/admin/addons.rst

@@ -17,8 +17,31 @@ translation project or component. Add-ons can be also installed site-wide in :re
 
 .. image:: /screenshots/addons.webp
 
+.. include:: /snippets/addon-events-autogenerated.rst
+
 .. include:: /snippets/addons-autogenerated.rst
 
+Obsolete add-ons
+++++++++++++++++
+
+.. _addon-weblate.xml.customize:
+
+Customize XML output
+--------------------
+
+.. versionadded:: 4.15
+
+.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`.
+
+.. _addon-weblate.yaml.customize:
+
+Customize YAML output
+---------------------
+
+.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`.
+
+.. include:: /snippets/addon-parameters-autogenerated.rst
+
 
 Customizing list of add-ons
 +++++++++++++++++++++++++++

docs/admin/management.rst

@@ -717,6 +717,12 @@ list_addons
 
 Lists add-ons in reStructuredText as a template for :doc:`/admin/addons`.
 
+.. weblate-admin-option:: --sections {events,addons,parameters}
+
+   Filter the generated output to just the add-on event sections, the built-in
+   add-on sections, or the shared add-on parameter sections. If omitted, all
+   generated sections are shown.
+
 .. seealso::
 
    :doc:`/contributing/documentation`
@@ -739,6 +745,18 @@ list_checks
 
 Lists quality checks in reStructuredText as a template for :doc:`/admin/checks` and :doc:`/user/checks`.
 
+.. weblate-admin-option:: --sections {checks,flags}
+
+   Filter the generated output to just the quality check sections or the
+   shared check flag sections. If omitted, all generated sections are shown.
+
+.. note::
+
+   Using ``--output`` requires selecting exactly one value in ``--sections`` so
+   each generated snippet is written to its own file. This matches the
+   :doc:`/contributing/documentation` workflow and the ``make -C docs
+   update-docs`` targets.
+
 .. seealso::
 
    :doc:`/contributing/documentation`

docs/changes.rst

@@ -38,6 +38,7 @@ Weblate 5.17
 * Screenshot and font upload forms now honor :setting:`ALLOWED_ASSET_SIZE` which now defaults to 10 MB.
 * Expanded :doc:`/security/threat-model` to cover webhook trust boundaries and delegated authorization boundaries, and clarified the instance-wide 2FA enforcement path in :doc:`/admin/auth`.
 * :ref:`manage-vcs-reset-reapply` now recreates missing translation files when possible and otherwise reports a clearer recovery error instead of failing later with a generic parse error.
+* Updated :doc:`/contributing/documentation` to describe the current ``make -C docs update-docs`` workflow for generated snippets.
 
 .. rubric:: Bug fixes
 
@@ -58,6 +59,7 @@ Weblate 5.17
 * Fixed false positive in :ref:`check-xml-chars-around-tags` for Arabic letter Waw ("و") adjacent to XML tags.
 * :ref:`addon-weblate.git.squash` better handle commits applied upstream.
 * :ref:`addon-weblate.cdn.cdnjs` validates parsed locations.
+* :wladmin:`list_checks` now requires exactly one ``--sections`` value when writing generated documentation to a file using ``--output``.
 * Asset downloads now enforce :setting:`ALLOWED_ASSET_DOMAINS` across HTTP redirects for screenshot URL uploads and remote HTML fetching in :ref:`addon-weblate.cdn.cdnjs`.
 * Improved security of :ref:`addon-weblate.webhook.webhook`.
 * Watched translations on the dashboard now use a stable language-aware ordering.

docs/contributing/documentation.rst

@@ -26,8 +26,19 @@ Building the documentation locally
 ----------------------------------
 
 Documentation can be also edited and built locally, the Python requirements are
-in the ``docs`` dependency group in :file:`pyproject.toml`. The build can be
-performed using :program:`ci/run-docs`.
+in the ``docs`` dependency group in :file:`pyproject.toml`. If you already use
+the full development environment, ``uv sync --all-extras --dev`` is enough. For
+documentation work only, ``uv sync --group docs`` is sufficient.
+
+The recommended local workflow is:
+
+.. code-block:: sh
+
+   make -C docs update-docs
+   ./ci/run-docs
+
+The :program:`ci/run-docs` wrapper builds the documentation with warnings
+treated as errors.
 
 .. hint::
 
@@ -38,19 +49,30 @@ Translating the documentation
 
 You can `translate the docs <https://hosted.weblate.org/projects/weblate/documentation/>`_.
 
-Documenting permissions, checks, add-ons and automatic suggestions
-------------------------------------------------------------------
+Updating generated documentation snippets
+-----------------------------------------
 
 Several documentation sections use templates generated from the code. The
-following management commands are available:
-
-* :wladmin:`list_addons`
-* :wladmin:`list_permissions`
-* :wladmin:`list_checks`
-* :wladmin:`list_machinery`
-* :wladmin:`list_file_format_params`
-* :wladmin:`list_change_events`
-
-All these commands output reStructuredText which is used as a template for the
-documentation. The easiest way to apply changes to the documentation is using
-visual diff in your editor.
+preferred way to refresh them is:
+
+.. code-block:: sh
+
+   make -C docs update-docs
+
+This target regenerates the snippets currently used by the documentation,
+including:
+
+* add-on events, built-in add-ons, and common add-on parameters
+* machine translation services
+* file format parameters and file format feature tables
+* permissions and built-in roles
+* checks and check flags
+
+Keep manually maintained text in the parent documentation page rather than
+adding it to autogenerated snippets. For example, :doc:`/admin/addons`
+includes three generated files for events, built-in add-ons, and common add-on
+parameters, while obsolete add-ons are maintained directly in the page.
+
+If you need to regenerate only one part, the individual management commands are
+documented in :doc:`/admin/management`, and the exact commands used by
+``update-docs`` are listed in :file:`docs/Makefile`.

docs/snippets/addon-events-autogenerated.rst

@@ -0,0 +1,110 @@
+
+.. AUTOGENERATED START: events
+.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually.
+
+Events that trigger add-ons
++++++++++++++++++++++++++++
+.. _addon-event-add-on-installation:
+
+Add-on installation
+-------------------
+
+Triggered when add-on is being installed.
+
+.. _addon-event-component-update:
+
+Component update
+----------------
+
+Triggered whenever a change happens in a component such as:
+
+* Strings are changed in the repository.
+* A string is added.
+* A new translation is added.
+
+.. _addon-event-daily:
+
+Daily
+-----
+
+Triggered daily, but add-ons usually split the daily load between components depending on :setting:`BACKGROUND_TASKS`.
+
+.. _addon-event-event-change:
+
+Event change
+------------
+
+Triggered after a Change event is created.
+
+.. _addon-event-repository-post-add:
+
+Repository post-add
+-------------------
+
+Triggered just after the new translation is added and committed.
+
+.. _addon-event-repository-post-commit:
+
+Repository post-commit
+----------------------
+
+Triggered just after the changes are committed.
+
+.. _addon-event-repository-post-push:
+
+Repository post-push
+--------------------
+
+Triggered just after the repository is pushed upstream.
+
+.. _addon-event-repository-post-update:
+
+Repository post-update
+----------------------
+
+Triggered whenever new changes are pulled from the upstream repository.
+
+.. _addon-event-repository-pre-commit:
+
+Repository pre-commit
+---------------------
+
+Triggered just before the changes are committed.
+
+.. _addon-event-repository-pre-push:
+
+Repository pre-push
+-------------------
+
+Triggered just before the repository is pushed upstream.
+
+.. _addon-event-repository-pre-update:
+
+Repository pre-update
+---------------------
+
+Triggered just before the repository update is attempted.
+
+.. _addon-event-unit-post-save:
+
+Unit post-save
+--------------
+
+Triggered just after the string is saved.
+
+.. _addon-event-unit-post-sync:
+
+Unit post-sync
+--------------
+
+Triggered after the string is synchronized with the VCS.
+
+.. _addon-event-unit-pre-create:
+
+Unit pre-create
+---------------
+
+Triggered just after the newly created string is saved.
+
+
+.. AUTOGENERATED END: events