Explicitly document all supported actions.

[oxr463]

The README.md file references the API spec, but this is not sufficient for documentation.

This is the full list at the time of writing this:

# Create a client per the README.md file
# then use tab completion in an interactive shell
client.
Display all 471 possibilities? (y or n)
client.action(
client.by_id(
client.by_id_authConfig(
client.by_id_auth_config(
client.by_id_catalog(
client.by_id_cisBenchmarkVersion(
client.by_id_cisConfig(
client.by_id_cis_benchmark_version(
client.by_id_cis_config(
client.by_id_cloudCredential(
client.by_id_cloud_credential(
client.by_id_cluster(
client.by_id_clusterAlert(
client.by_id_clusterAlertGroup(
client.by_id_clusterAlertRule(
client.by_id_clusterCatalog(
client.by_id_clusterLogging(
client.by_id_clusterMonitorGraph(
client.by_id_clusterRegistrationToken(
client.by_id_clusterRoleTemplateBinding(
client.by_id_clusterScan(
client.by_id_clusterTemplate(
client.by_id_clusterTemplateRevision(
client.by_id_cluster_alert(
client.by_id_cluster_alert_group(
client.by_id_cluster_alert_rule(
client.by_id_cluster_catalog(
client.by_id_cluster_logging(
client.by_id_cluster_monitor_graph(
client.by_id_cluster_registration_token(
client.by_id_cluster_role_template_binding(
client.by_id_cluster_scan(
client.by_id_cluster_template(
client.by_id_cluster_template_revision(
client.by_id_composeConfig(
client.by_id_compose_config(
client.by_id_dynamicSchema(
client.by_id_dynamic_schema(
client.by_id_etcdBackup(
client.by_id_etcd_backup(
client.by_id_feature(
client.by_id_fleetWorkspace(
client.by_id_fleet_workspace(
client.by_id_globalDns(
client.by_id_globalDnsProvider(
client.by_id_globalRole(
client.by_id_globalRoleBinding(
client.by_id_global_dns(
client.by_id_global_dns_provider(
client.by_id_global_role(
client.by_id_global_role_binding(
client.by_id_group(
client.by_id_groupMember(
client.by_id_group_member(
client.by_id_kontainerDriver(
client.by_id_kontainer_driver(
client.by_id_ldapConfig(
client.by_id_ldap_config(
client.by_id_managementSecret(
client.by_id_management_secret(
client.by_id_monitorMetric(
client.by_id_monitor_metric(
client.by_id_multiClusterApp(
client.by_id_multiClusterAppRevision(
client.by_id_multi_cluster_app(
client.by_id_multi_cluster_app_revision(
client.by_id_node(
client.by_id_nodeDriver(
client.by_id_nodePool(
client.by_id_nodeTemplate(
client.by_id_node_driver(
client.by_id_node_pool(
client.by_id_node_template(
client.by_id_notifier(
client.by_id_podSecurityPolicyTemplate(
client.by_id_podSecurityPolicyTemplateProjectBinding(
client.by_id_pod_security_policy_template(
client.by_id_pod_security_policy_template_project_binding(
client.by_id_preference(
client.by_id_principal(
client.by_id_project(
client.by_id_projectAlert(
client.by_id_projectAlertGroup(
client.by_id_projectAlertRule(
client.by_id_projectCatalog(
client.by_id_projectLogging(
client.by_id_projectMonitorGraph(
client.by_id_projectNetworkPolicy(
client.by_id_projectRoleTemplateBinding(
client.by_id_project_alert(
client.by_id_project_alert_group(
client.by_id_project_alert_rule(
client.by_id_project_catalog(
client.by_id_project_logging(
client.by_id_project_monitor_graph(
client.by_id_project_network_policy(
client.by_id_project_role_template_binding(
client.by_id_rkeAddon(
client.by_id_rkeK8sServiceOption(
client.by_id_rkeK8sSystemImage(
client.by_id_rke_addon(
client.by_id_rke_k8s_service_option(
client.by_id_rke_k8s_system_image(
client.by_id_roleTemplate(
client.by_id_role_template(
client.by_id_samlToken(
client.by_id_saml_token(
client.by_id_setting(
client.by_id_subscribe(
client.by_id_template(
client.by_id_templateVersion(
client.by_id_template_version(
client.by_id_token(
client.by_id_user(
client.create(
client.create_catalog(
client.create_cisBenchmarkVersion(
client.create_cisConfig(
client.create_cis_benchmark_version(
client.create_cis_config(
client.create_cloudCredential(
client.create_cloud_credential(
client.create_cluster(
client.create_clusterAlert(
client.create_clusterAlertGroup(
client.create_clusterAlertRule(
client.create_clusterCatalog(
client.create_clusterLogging(
client.create_clusterMonitorGraph(
client.create_clusterRegistrationToken(
client.create_clusterRoleTemplateBinding(
client.create_clusterTemplate(
client.create_clusterTemplateRevision(
client.create_cluster_alert(
client.create_cluster_alert_group(
client.create_cluster_alert_rule(
client.create_cluster_catalog(
client.create_cluster_logging(
client.create_cluster_monitor_graph(
client.create_cluster_registration_token(
client.create_cluster_role_template_binding(
client.create_cluster_template(
client.create_cluster_template_revision(
client.create_composeConfig(
client.create_compose_config(
client.create_dynamicSchema(
client.create_dynamic_schema(
client.create_etcdBackup(
client.create_etcd_backup(
client.create_feature(
client.create_fleetWorkspace(
client.create_fleet_workspace(
client.create_globalDns(
client.create_globalDnsProvider(
client.create_globalRole(
client.create_globalRoleBinding(
client.create_global_dns(
client.create_global_dns_provider(
client.create_global_role(
client.create_global_role_binding(
client.create_group(
client.create_groupMember(
client.create_group_member(
client.create_kontainerDriver(
client.create_kontainer_driver(
client.create_ldapConfig(
client.create_ldap_config(
client.create_managementSecret(
client.create_management_secret(
client.create_monitorMetric(
client.create_monitor_metric(
client.create_multiClusterApp(
client.create_multiClusterAppRevision(
client.create_multi_cluster_app(
client.create_multi_cluster_app_revision(
client.create_node(
client.create_nodeDriver(
client.create_nodePool(
client.create_nodeTemplate(
client.create_node_driver(
client.create_node_pool(
client.create_node_template(
client.create_notifier(
client.create_podSecurityPolicyTemplate(
client.create_podSecurityPolicyTemplateProjectBinding(
client.create_pod_security_policy_template(
client.create_pod_security_policy_template_project_binding(
client.create_preference(
client.create_project(
client.create_projectAlert(
client.create_projectAlertGroup(
client.create_projectAlertRule(
client.create_projectCatalog(
client.create_projectLogging(
client.create_projectMonitorGraph(
client.create_projectRoleTemplateBinding(
client.create_project_alert(
client.create_project_alert_group(
client.create_project_alert_rule(
client.create_project_catalog(
client.create_project_logging(
client.create_project_monitor_graph(
client.create_project_role_template_binding(
client.create_rkeAddon(
client.create_rkeK8sServiceOption(
client.create_rkeK8sSystemImage(
client.create_rke_addon(
client.create_rke_k8s_service_option(
client.create_rke_k8s_system_image(
client.create_roleTemplate(
client.create_role_template(
client.create_samlToken(
client.create_saml_token(
client.create_setting(
client.create_template(
client.create_templateVersion(
client.create_template_version(
client.create_token(
client.create_user(
client.delete(
client.list(
client.list_authConfig(
client.list_auth_config(
client.list_catalog(
client.list_cisBenchmarkVersion(
client.list_cisConfig(
client.list_cis_benchmark_version(
client.list_cis_config(
client.list_cloudCredential(
client.list_cloud_credential(
client.list_cluster(
client.list_clusterAlert(
client.list_clusterAlertGroup(
client.list_clusterAlertRule(
client.list_clusterCatalog(
client.list_clusterLogging(
client.list_clusterMonitorGraph(
client.list_clusterRegistrationToken(
client.list_clusterRoleTemplateBinding(
client.list_clusterScan(
client.list_clusterTemplate(
client.list_clusterTemplateRevision(
client.list_cluster_alert(
client.list_cluster_alert_group(
client.list_cluster_alert_rule(
client.list_cluster_catalog(
client.list_cluster_logging(
client.list_cluster_monitor_graph(
client.list_cluster_registration_token(
client.list_cluster_role_template_binding(
client.list_cluster_scan(
client.list_cluster_template(
client.list_cluster_template_revision(
client.list_composeConfig(
client.list_compose_config(
client.list_dynamicSchema(
client.list_dynamic_schema(
client.list_etcdBackup(
client.list_etcd_backup(
client.list_feature(
client.list_fleetWorkspace(
client.list_fleet_workspace(
client.list_globalDns(
client.list_globalDnsProvider(
client.list_globalRole(
client.list_globalRoleBinding(
client.list_global_dns(
client.list_global_dns_provider(
client.list_global_role(
client.list_global_role_binding(
client.list_group(
client.list_groupMember(
client.list_group_member(
client.list_kontainerDriver(
client.list_kontainer_driver(
client.list_ldapConfig(
client.list_ldap_config(
client.list_managementSecret(
client.list_management_secret(
client.list_monitorMetric(
client.list_monitor_metric(
client.list_multiClusterApp(
client.list_multiClusterAppRevision(
client.list_multi_cluster_app(
client.list_multi_cluster_app_revision(
client.list_node(
client.list_nodeDriver(
client.list_nodePool(
client.list_nodeTemplate(
client.list_node_driver(
client.list_node_pool(
client.list_node_template(
client.list_notifier(
client.list_podSecurityPolicyTemplate(
client.list_podSecurityPolicyTemplateProjectBinding(
client.list_pod_security_policy_template(
client.list_pod_security_policy_template_project_binding(
client.list_preference(
client.list_principal(
client.list_project(
client.list_projectAlert(
client.list_projectAlertGroup(
client.list_projectAlertRule(
client.list_projectCatalog(
client.list_projectLogging(
client.list_projectMonitorGraph(
client.list_projectNetworkPolicy(
client.list_projectRoleTemplateBinding(
client.list_project_alert(
client.list_project_alert_group(
client.list_project_alert_rule(
client.list_project_catalog(
client.list_project_logging(
client.list_project_monitor_graph(
client.list_project_network_policy(
client.list_project_role_template_binding(
client.list_rkeAddon(
client.list_rkeK8sServiceOption(
client.list_rkeK8sSystemImage(
client.list_rke_addon(
client.list_rke_k8s_service_option(
client.list_rke_k8s_system_image(
client.list_roleTemplate(
client.list_role_template(
client.list_samlToken(
client.list_saml_token(
client.list_setting(
client.list_subscribe(
client.list_template(
client.list_templateVersion(
client.list_template_version(
client.list_token(
client.list_user(
client.object_hook(
client.object_pairs_hook(
client.reload(
client.reload_schema(
client.schema
client.update(
client.update_by_id(
client.update_by_id_activeDirectoryConfig(
client.update_by_id_active_directory_config(
client.update_by_id_adfsConfig(
client.update_by_id_adfs_config(
client.update_by_id_authConfig(
client.update_by_id_auth_config(
client.update_by_id_azureADConfig(
client.update_by_id_azure_adconfig(
client.update_by_id_catalog(
client.update_by_id_cisBenchmarkVersion(
client.update_by_id_cisConfig(
client.update_by_id_cis_benchmark_version(
client.update_by_id_cis_config(
client.update_by_id_cloudCredential(
client.update_by_id_cloud_credential(
client.update_by_id_cluster(
client.update_by_id_clusterAlert(
client.update_by_id_clusterAlertGroup(
client.update_by_id_clusterAlertRule(
client.update_by_id_clusterCatalog(
client.update_by_id_clusterLogging(
client.update_by_id_clusterMonitorGraph(
client.update_by_id_clusterRegistrationToken(
client.update_by_id_clusterRoleTemplateBinding(
client.update_by_id_clusterTemplate(
client.update_by_id_clusterTemplateRevision(
client.update_by_id_cluster_alert(
client.update_by_id_cluster_alert_group(
client.update_by_id_cluster_alert_rule(
client.update_by_id_cluster_catalog(
client.update_by_id_cluster_logging(
client.update_by_id_cluster_monitor_graph(
client.update_by_id_cluster_registration_token(
client.update_by_id_cluster_role_template_binding(
client.update_by_id_cluster_template(
client.update_by_id_cluster_template_revision(
client.update_by_id_composeConfig(
client.update_by_id_compose_config(
client.update_by_id_dynamicSchema(
client.update_by_id_dynamic_schema(
client.update_by_id_etcdBackup(
client.update_by_id_etcd_backup(
client.update_by_id_feature(
client.update_by_id_fleetWorkspace(
client.update_by_id_fleet_workspace(
client.update_by_id_freeIpaConfig(
client.update_by_id_free_ipa_config(
client.update_by_id_githubConfig(
client.update_by_id_github_config(
client.update_by_id_globalDns(
client.update_by_id_globalDnsProvider(
client.update_by_id_globalRole(
client.update_by_id_globalRoleBinding(
client.update_by_id_global_dns(
client.update_by_id_global_dns_provider(
client.update_by_id_global_role(
client.update_by_id_global_role_binding(
client.update_by_id_googleOauthConfig(
client.update_by_id_google_oauth_config(
client.update_by_id_group(
client.update_by_id_groupMember(
client.update_by_id_group_member(
client.update_by_id_keyCloakConfig(
client.update_by_id_key_cloak_config(
client.update_by_id_kontainerDriver(
client.update_by_id_kontainer_driver(
client.update_by_id_ldapConfig(
client.update_by_id_ldap_config(
client.update_by_id_managementSecret(
client.update_by_id_management_secret(
client.update_by_id_monitorMetric(
client.update_by_id_monitor_metric(
client.update_by_id_multiClusterApp(
client.update_by_id_multiClusterAppRevision(
client.update_by_id_multi_cluster_app(
client.update_by_id_multi_cluster_app_revision(
client.update_by_id_node(
client.update_by_id_nodeDriver(
client.update_by_id_nodePool(
client.update_by_id_nodeTemplate(
client.update_by_id_node_driver(
client.update_by_id_node_pool(
client.update_by_id_node_template(
client.update_by_id_notifier(
client.update_by_id_oktaConfig(
client.update_by_id_okta_config(
client.update_by_id_openLdapConfig(
client.update_by_id_open_ldap_config(
client.update_by_id_pingConfig(
client.update_by_id_ping_config(
client.update_by_id_podSecurityPolicyTemplate(
client.update_by_id_pod_security_policy_template(
client.update_by_id_preference(
client.update_by_id_project(
client.update_by_id_projectAlert(
client.update_by_id_projectAlertGroup(
client.update_by_id_projectAlertRule(
client.update_by_id_projectCatalog(
client.update_by_id_projectLogging(
client.update_by_id_projectMonitorGraph(
client.update_by_id_projectRoleTemplateBinding(
client.update_by_id_project_alert(
client.update_by_id_project_alert_group(
client.update_by_id_project_alert_rule(
client.update_by_id_project_catalog(
client.update_by_id_project_logging(
client.update_by_id_project_monitor_graph(
client.update_by_id_project_role_template_binding(
client.update_by_id_rkeAddon(
client.update_by_id_rkeK8sServiceOption(
client.update_by_id_rkeK8sSystemImage(
client.update_by_id_rke_addon(
client.update_by_id_rke_k8s_service_option(
client.update_by_id_rke_k8s_system_image(
client.update_by_id_roleTemplate(
client.update_by_id_role_template(
client.update_by_id_samlToken(
client.update_by_id_saml_token(
client.update_by_id_setting(
client.update_by_id_shibbolethConfig(
client.update_by_id_shibboleth_config(
client.update_by_id_template(
client.update_by_id_templateContent(
client.update_by_id_templateVersion(
client.update_by_id_template_content(
client.update_by_id_template_version(
client.update_by_id_token(
client.update_by_id_user(
client.valid(
client.wait_success(
client.wait_transitioning(

gz#15364

[dramich]

Unfortunately, it's not possible to document all the actions as this depends on the version of rancher you are running. The client is dynamic based off the schemas rancher presents and thus anything we document will never be accurate.

[oxr463]

Unfortunately, it's not possible to document all the actions as this depends on the version of rancher you are running. The client is dynamic based off the schemas rancher presents and thus anything we document will never be accurate.

Then why not provide a means for the user to discover them? At the very least, you could include the steps I took above.

[vincent99]

This is a generic, dynamic client that knows nothing about the API is talking to in advance other than that it follows our basic structure. Some of the things you can talk to it with have nothing even to do with Rancher or Kubernetes and are written by unrelated third parties.

So putting in a list of the derived things it can do when pointed at one particular version of one product's API does not make a lot of sense. What you're proposing is very much like putting a list of websites cURL supports into their readme.

The normal way people "discover" those is by looking at the API directly (via api-ui). If you wanted to put something in the readme that (only) told someone HOW THEY could generate the list for themselves for the API they are pointing it at, that would make some sense.

[oxr463]

This is a generic, dynamic client that knows nothing about the API is talking to in advance other than that it follows our basic structure. Some of the things you can talk to it with have nothing even to do with Rancher or Kubernetes and are written by unrelated third parties.

So putting in a list of the derived things it can do when pointed at one particular version of one product's API does not make a lot of sense. What you're proposing is very much like putting a list of websites cURL supports into their readme.

The normal way people "discover" those is by looking at the API directly (via api-ui). If you wanted to put something in the readme that (only) told someone HOW THEY could generate the list for themselves for the API they are pointing it at, that would make some sense.

The README.md file states the following:

A Python client for the Rancher API

If this is for Kubernetes in general, or other third party APIs as you state, then this should be documented.

I don't see any documentation referencing "via api-ui" anywhere either.

The current lack of documentation is insufficient as-is.

Whatever can be done to improve this for users would be greatly appreciated.

[oxr463]

See also: rancher/rancher-docs#173