docs: freeze 6.3 CLI reference to static rST (OSMO-6482)

docs/Makefile

@@ -41,6 +41,13 @@ help:
 clean:
 	rm -rf _build
 
+# Freeze the CLI reference pages into static reStructuredText. Run this in the
+# environment of the branch being frozen (so the parser imports), then commit the
+# modified cli_*.rst files so the multiversion build renders them without
+# importing src.
+cli-rst:
+	python generate_cli_rst.py
+
 build:
 	export OSMO_DOMAIN=public && sphinx-build -b html . -w $(ERR_DIR)/build.log $(OUT_DIR)
 	export OSMO_DOMAIN=public && sphinx-build -b markdown . -w $(ERR_DIR)/markdown.log $(OUT_DIR)

docs/deployment_guide/references/config_cli/config_delete.rst

@@ -21,10 +21,52 @@
 osmo config delete
 ==================
 
-.. argparse-with-postprocess::
-   :module: src.cli.main_parser
-   :func: create_cli_parser
-   :prog: osmo
-   :path: config delete
-   :ref-prefix: cli_reference_config_delete
-   :argument-anchor:
+.. CLI-REFERENCE-GENERATED -- do not edit by hand; regenerate with: make -C docs cli-rst
+.. cli-source: module=src.cli.main_parser | func=create_cli_parser | prog=osmo | path=config delete | ref-prefix=cli_reference_config_delete | flags=argument-anchor
+
+Delete a named configuration or a specific config revision
+
+.. code-block:: text
+
+   usage: osmo config delete [-h] config_type [name] [--description DESCRIPTION] [--tags TAGS [TAGS ...]]
+
+.. _cli_reference_config_delete_positional_arguments:
+
+Positional Arguments
+--------------------
+
+``config_type``
+    Type of config to delete (CONFIG_TYPE) or CONFIG_TYPE:revision_number to delete a specific revision
+
+``name``
+    Name of the config to delete (required when not deleting a revision)
+
+.. _cli_reference_config_delete_named_arguments:
+
+Named Arguments
+---------------
+
+``--description, -d``
+    Description of the deletion (only used when deleting a named config)
+
+``--tags, -t``
+    Tags for the deletion (only used when deleting a named config)
+
+
+
+Available config types (CONFIG_TYPE): BACKEND, BACKEND_TEST, DATASET, GROUP_TEMPLATE, POD_TEMPLATE, POOL, RESOURCE_VALIDATION, ROLE
+
+.. rubric:: Examples
+
+Delete a named pool configuration::
+
+    osmo config delete POOL my-pool
+
+Delete a specific revision::
+
+    osmo config delete SERVICE:123
+
+Delete with description and tags::
+
+    osmo config delete BACKEND my-backend --description "Removing unused backend" --tags cleanup deprecated
+

docs/deployment_guide/references/config_cli/config_diff.rst

@@ -21,10 +21,45 @@
 osmo config diff
 ================
 
-.. argparse-with-postprocess::
-   :module: src.cli.main_parser
-   :func: create_cli_parser
-   :prog: osmo
-   :path: config diff
-   :ref-prefix: cli_reference_config_diff
-   :argument-anchor:
+.. CLI-REFERENCE-GENERATED -- do not edit by hand; regenerate with: make -C docs cli-rst
+.. cli-source: module=src.cli.main_parser | func=create_cli_parser | prog=osmo | path=config diff | ref-prefix=cli_reference_config_diff | flags=argument-anchor
+
+Show the difference between two config revisions
+
+Available config types (config_type): BACKEND, BACKEND_TEST, DATASET, GROUP_TEMPLATE, POD_TEMPLATE, POOL, RESOURCE_VALIDATION, ROLE, SERVICE, WORKFLOW
+
+.. code-block:: text
+
+   usage: osmo config diff [-h] first [second]
+
+.. _cli_reference_config_diff_positional_arguments:
+
+Positional Arguments
+--------------------
+
+``first``
+    First config to compare. Format: <config_type>[:<revision>] (e.g. BACKEND:3). If no revision is provided, uses the current revision.
+
+``second``
+    Second config to compare. Format: <config_type>[:<revision>] (e.g. BACKEND:6). If no revision is provided, uses the current revision.
+
+
+
+.. rubric:: Examples
+
+Show changes made to the workflow config since revision 15::
+
+  osmo config diff WORKFLOW:15
+
+.. image:: images/config_diff_workflow.png
+    :align: center
+    :class: mb-2
+
+Show changes made between two revisions of the service configuration::
+
+  osmo config diff SERVICE:14 SERVICE:15
+
+.. image:: images/config_diff_service.png
+    :align: center
+    :class: mb-2
+

docs/deployment_guide/references/config_cli/config_history.rst

@@ -21,10 +21,96 @@
 osmo config history
 ===================
 
-.. argparse-with-postprocess::
-   :module: src.cli.main_parser
-   :func: create_cli_parser
-   :prog: osmo
-   :path: config history
-   :ref-prefix: cli_reference_config_history
-   :argument-anchor:
+.. CLI-REFERENCE-GENERATED -- do not edit by hand; regenerate with: make -C docs cli-rst
+.. cli-source: module=src.cli.main_parser | func=create_cli_parser | prog=osmo | path=config history | ref-prefix=cli_reference_config_history | flags=argument-anchor
+
+List history of configuration changes
+
+.. code-block:: text
+
+   usage: osmo config history [-h] [config_type] [--offset OFFSET] [--count COUNT] [--order {asc,desc}] [--name NAME] [--revision REVISION] [--tags TAGS [TAGS ...]] [--at-timestamp AT_TIMESTAMP] [--created-before CREATED_BEFORE] [--created-after CREATED_AFTER] [--format-type {json,text}] [--fit-width]
+
+.. _cli_reference_config_history_positional_arguments:
+
+Positional Arguments
+--------------------
+
+``config_type``
+    Possible choices: BACKEND, BACKEND_TEST, DATASET, GROUP_TEMPLATE, POD_TEMPLATE, POOL, RESOURCE_VALIDATION, ROLE, SERVICE, WORKFLOW
+
+    Config type to show history for (CONFIG_TYPE)
+
+.. _cli_reference_config_history_named_arguments:
+
+Named Arguments
+---------------
+
+``--offset, -o``
+    Number of records to skip for pagination (default 0)
+
+    Default: ``0``
+
+``--count, -c``
+    Maximum number of records to return (default 20, max 1000)
+
+    Default: ``20``
+
+``--order``
+    Possible choices: asc, desc
+
+    Sort order by creation time (default asc)
+
+    Default: ``'asc'``
+
+``--name, -n``
+    Filter by changes to a particular config, e.g. "isaac-hil" pool
+
+``--revision, -r``
+    Filter by revision number
+
+``--tags``
+    Filter by tags
+
+``--at-timestamp``
+    Get config state at specific timestamp (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS) in current timezone
+
+``--created-before``
+    Filter by creation time before (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS) in current timezone
+
+``--created-after``
+    Filter by creation time after (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS) in current timezone
+
+``--format-type, -t``
+    Possible choices: json, text
+
+    Specify the output format type (default text)
+
+    Default: ``'text'``
+
+``--fit-width``
+    Fit the table width to the terminal width
+
+    Default: ``False``
+
+
+
+Available config types (CONFIG_TYPE): BACKEND, BACKEND_TEST, DATASET, GROUP_TEMPLATE, POD_TEMPLATE, POOL, RESOURCE_VALIDATION, ROLE, SERVICE, WORKFLOW
+
+.. rubric:: Examples
+
+View history in text format (default)::
+
+    osmo config history
+
+View history in JSON format with pagination::
+
+    osmo config history --format-type json --offset 10 --count 2
+
+View history for a specific configuration type::
+
+    osmo config history SERVICE
+
+View history for a specific time range::
+
+    osmo config history --created-after "2025-05-18" --created-before "2025-05-25"
+

docs/deployment_guide/references/config_cli/config_list.rst

@@ -21,10 +21,41 @@
 osmo config list
 ================
 
-.. argparse-with-postprocess::
-   :module: src.cli.main_parser
-   :func: create_cli_parser
-   :prog: osmo
-   :path: config list
-   :ref-prefix: cli_reference_config_list
-   :argument-anchor:
+.. CLI-REFERENCE-GENERATED -- do not edit by hand; regenerate with: make -C docs cli-rst
+.. cli-source: module=src.cli.main_parser | func=create_cli_parser | prog=osmo | path=config list | ref-prefix=cli_reference_config_list | flags=argument-anchor
+
+List current configuration revisions for each config type
+
+.. code-block:: text
+
+   usage: osmo config list [-h] [--format-type {json,text}] [--fit-width]
+
+.. _cli_reference_config_list_named_arguments:
+
+Named Arguments
+---------------
+
+``--format-type, -t``
+    Possible choices: json, text
+
+    Specify the output format type (default text)
+
+    Default: ``'text'``
+
+``--fit-width``
+    Fit the table width to the terminal width
+
+    Default: ``False``
+
+
+
+.. rubric:: Examples
+
+List configurations in text format (default)::
+
+    osmo config list
+
+List configurations in JSON format::
+
+    osmo config list --format-type json
+

docs/deployment_guide/references/config_cli/config_rollback.rst

@@ -21,10 +21,47 @@
 osmo config rollback
 ====================
 
-.. argparse-with-postprocess::
-   :module: src.cli.main_parser
-   :func: create_cli_parser
-   :prog: osmo
-   :path: config rollback
-   :ref-prefix: cli_reference_config_rollback
-   :argument-anchor:
+.. CLI-REFERENCE-GENERATED -- do not edit by hand; regenerate with: make -C docs cli-rst
+.. cli-source: module=src.cli.main_parser | func=create_cli_parser | prog=osmo | path=config rollback | ref-prefix=cli_reference_config_rollback | flags=argument-anchor
+
+Roll back a configuration to a previous revision
+
+When rolling back a configuration, the revision number is incremented by 1 and a new revision is created. The new revision will have the same data as the desired rollback revision.
+
+.. code-block:: text
+
+   usage: osmo config rollback [-h] revision [--description DESCRIPTION] [--tags TAGS [TAGS ...]]
+
+.. _cli_reference_config_rollback_positional_arguments:
+
+Positional Arguments
+--------------------
+
+``revision``
+    Revision to roll back to in format <CONFIG_TYPE>:<revision>, e.g. SERVICE:12
+
+.. _cli_reference_config_rollback_named_arguments:
+
+Named Arguments
+---------------
+
+``--description``
+    Optional description for the rollback action
+
+``--tags``
+    Optional tags for the rollback action
+
+
+
+Available config types (CONFIG_TYPE): BACKEND, BACKEND_TEST, DATASET, GROUP_TEMPLATE, POD_TEMPLATE, POOL, RESOURCE_VALIDATION, ROLE, SERVICE, WORKFLOW
+
+.. rubric:: Examples
+
+Roll back a service configuration::
+
+    osmo config rollback SERVICE:4
+
+Roll back with description and tags::
+
+    osmo config rollback BACKEND:7 --description "Rolling back to stable version" --tags rollback stable
+