diff --git a/docs/reference/api/agents.md b/docs/reference/api/agents.md index d241d8247c..4c8a3b86c7 100644 --- a/docs/reference/api/agents.md +++ b/docs/reference/api/agents.md @@ -1,4 +1,10 @@ -# Agents +--- +# Code generated by make gen. DO NOT EDIT. +title: Agents +description: "REST endpoints for the workspace agent daemon (`coder_agent`)." +--- + + Workspace agent endpoints. These power the workspace agent daemon defined by the `coder_agent` Terraform resource. This API is NOT the Coder Agents Chats API. For programmatic access to AI Coder Agents, see the Chats API. diff --git a/docs/reference/api/aigateway.md b/docs/reference/api/aigateway.md index 18d1f862e3..22d8cd7235 100644 --- a/docs/reference/api/aigateway.md +++ b/docs/reference/api/aigateway.md @@ -1,4 +1,9 @@ -# AI Gateway +--- +# Code generated by make gen. DO NOT EDIT. +title: AI Gateway +--- + + ## List AI Gateway clients diff --git a/docs/reference/api/aiproviders.md b/docs/reference/api/aiproviders.md index fe9be024bf..cca295406a 100644 --- a/docs/reference/api/aiproviders.md +++ b/docs/reference/api/aiproviders.md @@ -1,4 +1,9 @@ -# AI Providers +--- +# Code generated by make gen. DO NOT EDIT. +title: AI Providers +--- + + ## List AI providers diff --git a/docs/reference/api/applications.md b/docs/reference/api/applications.md index af1d3b5031..f018dce003 100644 --- a/docs/reference/api/applications.md +++ b/docs/reference/api/applications.md @@ -1,4 +1,9 @@ -# Applications +--- +# Code generated by make gen. DO NOT EDIT. +title: Applications +--- + + ## Redirect to URI with encrypted API key diff --git a/docs/reference/api/audit.md b/docs/reference/api/audit.md index 06a7057fb7..596aff7c49 100644 --- a/docs/reference/api/audit.md +++ b/docs/reference/api/audit.md @@ -1,4 +1,9 @@ -# Audit +--- +# Code generated by make gen. DO NOT EDIT. +title: Audit +--- + + ## Get audit logs diff --git a/docs/reference/api/authentication.md b/docs/reference/api/authentication.md index aef03ae6ee..f021d15640 100644 --- a/docs/reference/api/authentication.md +++ b/docs/reference/api/authentication.md @@ -1,4 +1,9 @@ -# Authentication +--- +# Code generated by make gen. DO NOT EDIT. +title: Authentication +--- + + Long-lived tokens can be generated to perform actions on behalf of your user account: diff --git a/docs/reference/api/authorization.md b/docs/reference/api/authorization.md index 1580bbcef0..52baefb7da 100644 --- a/docs/reference/api/authorization.md +++ b/docs/reference/api/authorization.md @@ -1,4 +1,9 @@ -# Authorization +--- +# Code generated by make gen. DO NOT EDIT. +title: Authorization +--- + + ## List API key scopes diff --git a/docs/reference/api/builds.md b/docs/reference/api/builds.md index bdf1c8683c..1d835e1088 100644 --- a/docs/reference/api/builds.md +++ b/docs/reference/api/builds.md @@ -1,4 +1,9 @@ -# Builds +--- +# Code generated by make gen. DO NOT EDIT. +title: Builds +--- + + ## Get workspace build by user, workspace name, and build number diff --git a/docs/reference/api/chat.md b/docs/reference/api/chat.md deleted file mode 100644 index 279df4ad79..0000000000 --- a/docs/reference/api/chat.md +++ /dev/null @@ -1 +0,0 @@ -# Chat diff --git a/docs/reference/api/chats.md b/docs/reference/api/chats.md index 8cd963f356..dd50f948ca 100644 --- a/docs/reference/api/chats.md +++ b/docs/reference/api/chats.md @@ -1,4 +1,12 @@ -# Chats +--- +# Code generated by make gen. DO NOT EDIT. +title: Chats +description: "REST endpoints for Coder Agents Chats API (programmatic agent sessions)." +state: + - early access +--- + + Programmatic API for Coder Agents (the user-facing "Coder Agents" / "Chats" product). Use these endpoints to create, list, and manage AI coding agent sessions. diff --git a/docs/reference/api/debug.md b/docs/reference/api/debug.md index 235f468e82..5cd239e22e 100644 --- a/docs/reference/api/debug.md +++ b/docs/reference/api/debug.md @@ -1,4 +1,9 @@ -# Debug +--- +# Code generated by make gen. DO NOT EDIT. +title: Debug +--- + + ## Debug Info Wireguard Coordinator diff --git a/docs/reference/api/enterprise.md b/docs/reference/api/enterprise.md index 92da32c835..a6c7114b16 100644 --- a/docs/reference/api/enterprise.md +++ b/docs/reference/api/enterprise.md @@ -1,4 +1,9 @@ -# Enterprise +--- +# Code generated by make gen. DO NOT EDIT. +title: Enterprise +--- + + ## OAuth2 authorization server metadata diff --git a/docs/reference/api/files.md b/docs/reference/api/files.md index cd8abd99e5..0502f6fdf1 100644 --- a/docs/reference/api/files.md +++ b/docs/reference/api/files.md @@ -1,4 +1,9 @@ -# Files +--- +# Code generated by make gen. DO NOT EDIT. +title: Files +--- + + ## Upload file diff --git a/docs/reference/api/general.md b/docs/reference/api/general.md index 5d972b733c..6b708bca40 100644 --- a/docs/reference/api/general.md +++ b/docs/reference/api/general.md @@ -1,4 +1,9 @@ -# General +--- +# Code generated by make gen. DO NOT EDIT. +title: General +--- + + ## API root handler diff --git a/docs/reference/api/git.md b/docs/reference/api/git.md index 8c5c996e84..2a4d2b8275 100644 --- a/docs/reference/api/git.md +++ b/docs/reference/api/git.md @@ -1,4 +1,9 @@ -# Git +--- +# Code generated by make gen. DO NOT EDIT. +title: Git +--- + + ## Get user external auths diff --git a/docs/reference/api/index.md b/docs/reference/api/index.md index c8434f20bc..5e7911d8e9 100644 --- a/docs/reference/api/index.md +++ b/docs/reference/api/index.md @@ -1,4 +1,11 @@ -# API +--- +# Code generated by make gen. DO NOT EDIT. +title: REST API +description: "Reference for the Coder REST API, including endpoints, authentication, and schemas." +icon_path: "./images/icons/api.svg" +--- + + Get started with the Coder API: diff --git a/docs/reference/api/initscript.md b/docs/reference/api/initscript.md index a86cc5f81c..0870ff9abf 100644 --- a/docs/reference/api/initscript.md +++ b/docs/reference/api/initscript.md @@ -1,4 +1,9 @@ -# InitScript +--- +# Code generated by make gen. DO NOT EDIT. +title: InitScript +--- + + ## Get agent init script diff --git a/docs/reference/api/insights.md b/docs/reference/api/insights.md index eb42bc040c..fc62bbcae8 100644 --- a/docs/reference/api/insights.md +++ b/docs/reference/api/insights.md @@ -1,4 +1,9 @@ -# Insights +--- +# Code generated by make gen. DO NOT EDIT. +title: Insights +--- + + ## Get deployment DAUs diff --git a/docs/reference/api/members.md b/docs/reference/api/members.md index 6660b4a138..1ded61bd0e 100644 --- a/docs/reference/api/members.md +++ b/docs/reference/api/members.md @@ -1,4 +1,9 @@ -# Members +--- +# Code generated by make gen. DO NOT EDIT. +title: Members +--- + + ## List organization members diff --git a/docs/reference/api/notifications.md b/docs/reference/api/notifications.md index 176f6d683e..9a826056b6 100644 --- a/docs/reference/api/notifications.md +++ b/docs/reference/api/notifications.md @@ -1,4 +1,9 @@ -# Notifications +--- +# Code generated by make gen. DO NOT EDIT. +title: Notifications +--- + + ## Send a custom notification diff --git a/docs/reference/api/organizations.md b/docs/reference/api/organizations.md index 2f0dbf1625..f6de2609fa 100644 --- a/docs/reference/api/organizations.md +++ b/docs/reference/api/organizations.md @@ -1,4 +1,9 @@ -# Organizations +--- +# Code generated by make gen. DO NOT EDIT. +title: Organizations +--- + + ## Get organizations diff --git a/docs/reference/api/portsharing.md b/docs/reference/api/portsharing.md index 08c8deb4c0..b4e06113a0 100644 --- a/docs/reference/api/portsharing.md +++ b/docs/reference/api/portsharing.md @@ -1,4 +1,9 @@ -# PortSharing +--- +# Code generated by make gen. DO NOT EDIT. +title: PortSharing +--- + + ## Get workspace agent port shares diff --git a/docs/reference/api/prebuilds.md b/docs/reference/api/prebuilds.md index 6f6a085000..5d16f9d8e3 100644 --- a/docs/reference/api/prebuilds.md +++ b/docs/reference/api/prebuilds.md @@ -1,4 +1,9 @@ -# Prebuilds +--- +# Code generated by make gen. DO NOT EDIT. +title: Prebuilds +--- + + ## Get prebuilds settings diff --git a/docs/reference/api/provisioning.md b/docs/reference/api/provisioning.md index d087f00be3..03512df612 100644 --- a/docs/reference/api/provisioning.md +++ b/docs/reference/api/provisioning.md @@ -1,4 +1,9 @@ -# Provisioning +--- +# Code generated by make gen. DO NOT EDIT. +title: Provisioning +--- + + ## Get provisioner daemons diff --git a/docs/reference/api/schemas.md b/docs/reference/api/schemas.md index d51bd77dcc..1e6dbe6e0e 100644 --- a/docs/reference/api/schemas.md +++ b/docs/reference/api/schemas.md @@ -1,4 +1,9 @@ -# Schemas +--- +# Code generated by make gen. DO NOT EDIT. +title: Schemas +--- + + ## agentsdk.AWSInstanceIdentityToken diff --git a/docs/reference/api/secrets.md b/docs/reference/api/secrets.md index d1eee9875d..b7b16e5eae 100644 --- a/docs/reference/api/secrets.md +++ b/docs/reference/api/secrets.md @@ -1,4 +1,9 @@ -# Secrets +--- +# Code generated by make gen. DO NOT EDIT. +title: Secrets +--- + + ## List user secrets diff --git a/docs/reference/api/tasks.md b/docs/reference/api/tasks.md index 5de76291ce..d51e2b6898 100644 --- a/docs/reference/api/tasks.md +++ b/docs/reference/api/tasks.md @@ -1,4 +1,9 @@ -# Tasks +--- +# Code generated by make gen. DO NOT EDIT. +title: Tasks +--- + + ## List AI tasks diff --git a/docs/reference/api/templatebuilder.md b/docs/reference/api/templatebuilder.md index 5172995b8f..183c7c2351 100644 --- a/docs/reference/api/templatebuilder.md +++ b/docs/reference/api/templatebuilder.md @@ -1,4 +1,9 @@ -# TemplateBuilder +--- +# Code generated by make gen. DO NOT EDIT. +title: TemplateBuilder +--- + + ## List template builder base templates diff --git a/docs/reference/api/templates.md b/docs/reference/api/templates.md index cdc73eff27..8c5387da74 100644 --- a/docs/reference/api/templates.md +++ b/docs/reference/api/templates.md @@ -1,4 +1,9 @@ -# Templates +--- +# Code generated by make gen. DO NOT EDIT. +title: Templates +--- + + ## Get templates by organization diff --git a/docs/reference/api/users.md b/docs/reference/api/users.md index 788c51f196..ca780e6cf0 100644 --- a/docs/reference/api/users.md +++ b/docs/reference/api/users.md @@ -1,4 +1,9 @@ -# Users +--- +# Code generated by make gen. DO NOT EDIT. +title: Users +--- + + ## Get users diff --git a/docs/reference/api/workspaceproxies.md b/docs/reference/api/workspaceproxies.md index 85dc146149..8b15e3a9d9 100644 --- a/docs/reference/api/workspaceproxies.md +++ b/docs/reference/api/workspaceproxies.md @@ -1,4 +1,9 @@ -# WorkspaceProxies +--- +# Code generated by make gen. DO NOT EDIT. +title: WorkspaceProxies +--- + + ## Get site-wide regions for workspace connections diff --git a/docs/reference/api/workspaces.md b/docs/reference/api/workspaces.md index eb2787b06b..7a22c111e5 100644 --- a/docs/reference/api/workspaces.md +++ b/docs/reference/api/workspaces.md @@ -1,4 +1,9 @@ -# Workspaces +--- +# Code generated by make gen. DO NOT EDIT. +title: Workspaces +--- + + ## Create user workspace by organization diff --git a/docs/reference/cli/agent-firewall.md b/docs/reference/cli/agent-firewall.md index f68b381607..c4e849c072 100644 --- a/docs/reference/cli/agent-firewall.md +++ b/docs/reference/cli/agent-firewall.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: agent-firewall +description: Network isolation tool for monitoring and restricting HTTP/HTTPS requests +--- + -# agent-firewall Network isolation tool for monitoring and restricting HTTP/HTTPS requests diff --git a/docs/reference/cli/ai-gateway.md b/docs/reference/cli/ai-gateway.md index 1b8d2401d3..9becac92f6 100644 --- a/docs/reference/cli/ai-gateway.md +++ b/docs/reference/cli/ai-gateway.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ai-gateway +description: Manage AI Gateway +--- + -# ai-gateway Manage AI Gateway diff --git a/docs/reference/cli/ai-gateway_keys.md b/docs/reference/cli/ai-gateway_keys.md index c2e258ac6d..aee8a20cc2 100644 --- a/docs/reference/cli/ai-gateway_keys.md +++ b/docs/reference/cli/ai-gateway_keys.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ai-gateway keys +description: Manage AI Gateway keys +--- + -# ai-gateway keys Manage AI Gateway keys diff --git a/docs/reference/cli/ai-gateway_keys_create.md b/docs/reference/cli/ai-gateway_keys_create.md index 7f6b967684..64ce4a0bb1 100644 --- a/docs/reference/cli/ai-gateway_keys_create.md +++ b/docs/reference/cli/ai-gateway_keys_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ai-gateway keys create +description: Create an AI Gateway key +--- + -# ai-gateway keys create Create an AI Gateway key diff --git a/docs/reference/cli/ai-gateway_keys_delete.md b/docs/reference/cli/ai-gateway_keys_delete.md index eee21bc0a2..753f6c7fe9 100644 --- a/docs/reference/cli/ai-gateway_keys_delete.md +++ b/docs/reference/cli/ai-gateway_keys_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ai-gateway keys delete +description: Delete an AI Gateway key +--- + -# ai-gateway keys delete Delete an AI Gateway key diff --git a/docs/reference/cli/ai-gateway_keys_list.md b/docs/reference/cli/ai-gateway_keys_list.md index babe66b416..6a8be96d7d 100644 --- a/docs/reference/cli/ai-gateway_keys_list.md +++ b/docs/reference/cli/ai-gateway_keys_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ai-gateway keys list +description: List AI Gateway keys +--- + -# ai-gateway keys list List AI Gateway keys diff --git a/docs/reference/cli/ai-gateway_start.md b/docs/reference/cli/ai-gateway_start.md index 8dcc63a641..b3f9d6c663 100644 --- a/docs/reference/cli/ai-gateway_start.md +++ b/docs/reference/cli/ai-gateway_start.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ai-gateway start +description: Run a standalone AI Gateway server +--- + -# ai-gateway start Run a standalone AI Gateway server diff --git a/docs/reference/cli/autoupdate.md b/docs/reference/cli/autoupdate.md index 6446804c42..a01df7ddb1 100644 --- a/docs/reference/cli/autoupdate.md +++ b/docs/reference/cli/autoupdate.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: autoupdate +description: Toggle auto-update policy for a workspace +--- + -# autoupdate Toggle auto-update policy for a workspace diff --git a/docs/reference/cli/completion.md b/docs/reference/cli/completion.md index 1d14fc2aa2..a0353840b0 100644 --- a/docs/reference/cli/completion.md +++ b/docs/reference/cli/completion.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: completion +description: Install or update shell completion scripts for the detected or chosen shell. +--- + -# completion Install or update shell completion scripts for the detected or chosen shell. diff --git a/docs/reference/cli/config-ssh.md b/docs/reference/cli/config-ssh.md index a169c9fe30..1ca8fa5ca3 100644 --- a/docs/reference/cli/config-ssh.md +++ b/docs/reference/cli/config-ssh.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: config-ssh +description: "Add an SSH Host entry for your workspaces \"ssh workspace.coder\"" +--- + -# config-ssh Add an SSH Host entry for your workspaces "ssh workspace.coder" diff --git a/docs/reference/cli/create.md b/docs/reference/cli/create.md index 7e6fd1ce2c..2130fa9de5 100644 --- a/docs/reference/cli/create.md +++ b/docs/reference/cli/create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: create +description: Create a workspace +--- + -# create Create a workspace diff --git a/docs/reference/cli/delete.md b/docs/reference/cli/delete.md index 79d9401ccf..3cdb432b41 100644 --- a/docs/reference/cli/delete.md +++ b/docs/reference/cli/delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: delete +description: Delete a workspace +--- + -# delete Delete a workspace diff --git a/docs/reference/cli/dotfiles.md b/docs/reference/cli/dotfiles.md index 81ef8386c6..82b4b99624 100644 --- a/docs/reference/cli/dotfiles.md +++ b/docs/reference/cli/dotfiles.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: dotfiles +description: Personalize your workspace by applying a canonical dotfiles repository +--- + -# dotfiles Personalize your workspace by applying a canonical dotfiles repository diff --git a/docs/reference/cli/external-auth.md b/docs/reference/cli/external-auth.md index 5347bfd34e..c93e79f552 100644 --- a/docs/reference/cli/external-auth.md +++ b/docs/reference/cli/external-auth.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: external-auth +description: Manage external authentication +--- + -# external-auth Manage external authentication diff --git a/docs/reference/cli/external-auth_access-token.md b/docs/reference/cli/external-auth_access-token.md index 1422b0a8de..bf059734ba 100644 --- a/docs/reference/cli/external-auth_access-token.md +++ b/docs/reference/cli/external-auth_access-token.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: external-auth access-token +description: Print auth for an external provider +--- + -# external-auth access-token Print auth for an external provider diff --git a/docs/reference/cli/external-workspaces.md b/docs/reference/cli/external-workspaces.md index 5e1f27a779..1b8615285e 100644 --- a/docs/reference/cli/external-workspaces.md +++ b/docs/reference/cli/external-workspaces.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: external-workspaces +description: Create or manage external workspaces +--- + -# external-workspaces Create or manage external workspaces diff --git a/docs/reference/cli/external-workspaces_agent-instructions.md b/docs/reference/cli/external-workspaces_agent-instructions.md index d284a48de7..9815ba5563 100644 --- a/docs/reference/cli/external-workspaces_agent-instructions.md +++ b/docs/reference/cli/external-workspaces_agent-instructions.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: external-workspaces agent-instructions +description: Get the instructions for an external agent +--- + -# external-workspaces agent-instructions Get the instructions for an external agent diff --git a/docs/reference/cli/external-workspaces_create.md b/docs/reference/cli/external-workspaces_create.md index cb15a0fc6d..b1d8ddee5e 100644 --- a/docs/reference/cli/external-workspaces_create.md +++ b/docs/reference/cli/external-workspaces_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: external-workspaces create +description: Create a new external workspace +--- + -# external-workspaces create Create a new external workspace diff --git a/docs/reference/cli/external-workspaces_list.md b/docs/reference/cli/external-workspaces_list.md index 061aaa29d7..1daf5b2b5b 100644 --- a/docs/reference/cli/external-workspaces_list.md +++ b/docs/reference/cli/external-workspaces_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: external-workspaces list +description: List external workspaces +--- + -# external-workspaces list List external workspaces diff --git a/docs/reference/cli/favorite.md b/docs/reference/cli/favorite.md index 97ff6fde44..336c134f10 100644 --- a/docs/reference/cli/favorite.md +++ b/docs/reference/cli/favorite.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: favorite +description: Add a workspace to your favorites +--- + -# favorite Add a workspace to your favorites diff --git a/docs/reference/cli/features.md b/docs/reference/cli/features.md index 1ba187f964..c19291f228 100644 --- a/docs/reference/cli/features.md +++ b/docs/reference/cli/features.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: features +description: List Enterprise features +--- + -# features List Enterprise features diff --git a/docs/reference/cli/features_list.md b/docs/reference/cli/features_list.md index a1aab1d165..17cb679177 100644 --- a/docs/reference/cli/features_list.md +++ b/docs/reference/cli/features_list.md @@ -1,5 +1,9 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: features list +--- + -# features list Aliases: diff --git a/docs/reference/cli/groups.md b/docs/reference/cli/groups.md index a036d646ab..c909f6b425 100644 --- a/docs/reference/cli/groups.md +++ b/docs/reference/cli/groups.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: groups +description: Manage groups +--- + -# groups Manage groups diff --git a/docs/reference/cli/groups_create.md b/docs/reference/cli/groups_create.md index 4274a681a5..368f7095e3 100644 --- a/docs/reference/cli/groups_create.md +++ b/docs/reference/cli/groups_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: groups create +description: Create a user group +--- + -# groups create Create a user group diff --git a/docs/reference/cli/groups_delete.md b/docs/reference/cli/groups_delete.md index 2135fb635c..a825db2807 100644 --- a/docs/reference/cli/groups_delete.md +++ b/docs/reference/cli/groups_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: groups delete +description: Delete a user group +--- + -# groups delete Delete a user group diff --git a/docs/reference/cli/groups_edit.md b/docs/reference/cli/groups_edit.md index 356a7eea4e..2c345ee4bf 100644 --- a/docs/reference/cli/groups_edit.md +++ b/docs/reference/cli/groups_edit.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: groups edit +description: Edit a user group +--- + -# groups edit Edit a user group diff --git a/docs/reference/cli/groups_list.md b/docs/reference/cli/groups_list.md index c76e8b382e..00bbef6b06 100644 --- a/docs/reference/cli/groups_list.md +++ b/docs/reference/cli/groups_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: groups list +description: List user groups +--- + -# groups list List user groups diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 219673d771..23f33b0a0f 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -1,5 +1,11 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: Command Line +description: "Reference for the Coder command-line interface, with usage and flags for every command." +icon_path: "./images/icons/terminal.svg" +--- + -# coder ## Usage diff --git a/docs/reference/cli/licenses.md b/docs/reference/cli/licenses.md index 8e71f01aba..3dcb24dd4c 100644 --- a/docs/reference/cli/licenses.md +++ b/docs/reference/cli/licenses.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: licenses +description: "Add, delete, and list licenses" +--- + -# licenses Add, delete, and list licenses diff --git a/docs/reference/cli/licenses_add.md b/docs/reference/cli/licenses_add.md index 5562f5f49b..7d04b56e50 100644 --- a/docs/reference/cli/licenses_add.md +++ b/docs/reference/cli/licenses_add.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: licenses add +description: Add license to Coder deployment +--- + -# licenses add Add license to Coder deployment diff --git a/docs/reference/cli/licenses_delete.md b/docs/reference/cli/licenses_delete.md index 9a24e520e6..974a7d6da9 100644 --- a/docs/reference/cli/licenses_delete.md +++ b/docs/reference/cli/licenses_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: licenses delete +description: Delete license by ID +--- + -# licenses delete Delete license by ID diff --git a/docs/reference/cli/licenses_list.md b/docs/reference/cli/licenses_list.md index 17311df2d6..f5f4a03734 100644 --- a/docs/reference/cli/licenses_list.md +++ b/docs/reference/cli/licenses_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: licenses list +description: "List licenses (including expired)" +--- + -# licenses list List licenses (including expired) diff --git a/docs/reference/cli/list.md b/docs/reference/cli/list.md index 5911785b87..0878cb73c7 100644 --- a/docs/reference/cli/list.md +++ b/docs/reference/cli/list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: list +description: List workspaces +--- + -# list List workspaces diff --git a/docs/reference/cli/login.md b/docs/reference/cli/login.md index 4a0eb2eb57..d54f94e47b 100644 --- a/docs/reference/cli/login.md +++ b/docs/reference/cli/login.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: login +description: Authenticate with Coder deployment +--- + -# login Authenticate with Coder deployment diff --git a/docs/reference/cli/login_token.md b/docs/reference/cli/login_token.md index 70f7457e54..6354c83c4d 100644 --- a/docs/reference/cli/login_token.md +++ b/docs/reference/cli/login_token.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: login token +description: Print the current session token +--- + -# login token Print the current session token diff --git a/docs/reference/cli/logout.md b/docs/reference/cli/logout.md index a56ed9f52b..4bfefd16bb 100644 --- a/docs/reference/cli/logout.md +++ b/docs/reference/cli/logout.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: logout +description: Unauthenticate your local session +--- + -# logout Unauthenticate your local session diff --git a/docs/reference/cli/logs.md b/docs/reference/cli/logs.md index 347378270f..5b1814d79a 100644 --- a/docs/reference/cli/logs.md +++ b/docs/reference/cli/logs.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: logs +description: View logs for a workspace +--- + -# logs View logs for a workspace diff --git a/docs/reference/cli/netcheck.md b/docs/reference/cli/netcheck.md index 219f6fa16b..5df25cd52f 100644 --- a/docs/reference/cli/netcheck.md +++ b/docs/reference/cli/netcheck.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: netcheck +description: Print network debug information for DERP and STUN +--- + -# netcheck Print network debug information for DERP and STUN diff --git a/docs/reference/cli/notifications.md b/docs/reference/cli/notifications.md index bb471754e4..32ef81fe4d 100644 --- a/docs/reference/cli/notifications.md +++ b/docs/reference/cli/notifications.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: notifications +description: Manage Coder notifications +--- + -# notifications Manage Coder notifications diff --git a/docs/reference/cli/notifications_custom.md b/docs/reference/cli/notifications_custom.md index 9b8eff39fc..470ab927e2 100644 --- a/docs/reference/cli/notifications_custom.md +++ b/docs/reference/cli/notifications_custom.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: notifications custom +description: Send a custom notification +--- + -# notifications custom Send a custom notification diff --git a/docs/reference/cli/notifications_pause.md b/docs/reference/cli/notifications_pause.md index 5bac0c2f9e..92edf43880 100644 --- a/docs/reference/cli/notifications_pause.md +++ b/docs/reference/cli/notifications_pause.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: notifications pause +description: Pause notifications +--- + -# notifications pause Pause notifications diff --git a/docs/reference/cli/notifications_resume.md b/docs/reference/cli/notifications_resume.md index 79ec60ba54..eedc58a094 100644 --- a/docs/reference/cli/notifications_resume.md +++ b/docs/reference/cli/notifications_resume.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: notifications resume +description: Resume notifications +--- + -# notifications resume Resume notifications diff --git a/docs/reference/cli/notifications_test.md b/docs/reference/cli/notifications_test.md index 794c3e0d35..b6b91d10fe 100644 --- a/docs/reference/cli/notifications_test.md +++ b/docs/reference/cli/notifications_test.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: notifications test +description: Send a test notification +--- + -# notifications test Send a test notification diff --git a/docs/reference/cli/oauth2-provider.md b/docs/reference/cli/oauth2-provider.md index e3ea5b7638..566f2681d5 100644 --- a/docs/reference/cli/oauth2-provider.md +++ b/docs/reference/cli/oauth2-provider.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: oauth2-provider +description: Manage Coder OAuth2 provider settings +--- + -# oauth2-provider Manage Coder OAuth2 provider settings diff --git a/docs/reference/cli/oauth2-provider_dcr.md b/docs/reference/cli/oauth2-provider_dcr.md index 24904d0334..38643b6848 100644 --- a/docs/reference/cli/oauth2-provider_dcr.md +++ b/docs/reference/cli/oauth2-provider_dcr.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: oauth2-provider dcr +description: "Manage OAuth2 dynamic client registration (RFC 7591)" +--- + -# oauth2-provider dcr Manage OAuth2 dynamic client registration (RFC 7591) diff --git a/docs/reference/cli/oauth2-provider_dcr_disable.md b/docs/reference/cli/oauth2-provider_dcr_disable.md index 689dacdfa4..893655664a 100644 --- a/docs/reference/cli/oauth2-provider_dcr_disable.md +++ b/docs/reference/cli/oauth2-provider_dcr_disable.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: oauth2-provider dcr disable +description: Disable OAuth2 dynamic client registration +--- + -# oauth2-provider dcr disable Disable OAuth2 dynamic client registration diff --git a/docs/reference/cli/oauth2-provider_dcr_enable.md b/docs/reference/cli/oauth2-provider_dcr_enable.md index 282b94c6c9..123a8a5113 100644 --- a/docs/reference/cli/oauth2-provider_dcr_enable.md +++ b/docs/reference/cli/oauth2-provider_dcr_enable.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: oauth2-provider dcr enable +description: Enable OAuth2 dynamic client registration +--- + -# oauth2-provider dcr enable Enable OAuth2 dynamic client registration diff --git a/docs/reference/cli/open.md b/docs/reference/cli/open.md index 0f54e4648e..9d756d856f 100644 --- a/docs/reference/cli/open.md +++ b/docs/reference/cli/open.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: open +description: Open a workspace +--- + -# open Open a workspace diff --git a/docs/reference/cli/open_app.md b/docs/reference/cli/open_app.md index 1edd274815..3301b0d380 100644 --- a/docs/reference/cli/open_app.md +++ b/docs/reference/cli/open_app.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: open app +description: Open a workspace application. +--- + -# open app Open a workspace application. diff --git a/docs/reference/cli/open_vscode.md b/docs/reference/cli/open_vscode.md index 2b1e80dfbe..207c94cf48 100644 --- a/docs/reference/cli/open_vscode.md +++ b/docs/reference/cli/open_vscode.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: open vscode +description: Open a workspace in VS Code Desktop +--- + -# open vscode Open a workspace in VS Code Desktop diff --git a/docs/reference/cli/organizations.md b/docs/reference/cli/organizations.md index e487735e8c..02ad6af84e 100644 --- a/docs/reference/cli/organizations.md +++ b/docs/reference/cli/organizations.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations +description: Organization related commands +--- + -# organizations Organization related commands diff --git a/docs/reference/cli/organizations_create.md b/docs/reference/cli/organizations_create.md index 414edd9488..72f0d0f1b3 100644 --- a/docs/reference/cli/organizations_create.md +++ b/docs/reference/cli/organizations_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations create +description: Create a new organization. +--- + -# organizations create Create a new organization. diff --git a/docs/reference/cli/organizations_delete.md b/docs/reference/cli/organizations_delete.md index da8a1c717d..ccd47507d5 100644 --- a/docs/reference/cli/organizations_delete.md +++ b/docs/reference/cli/organizations_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations delete +description: Delete an organization +--- + -# organizations delete Delete an organization diff --git a/docs/reference/cli/organizations_list.md b/docs/reference/cli/organizations_list.md index c1335b7f8b..2bec17415c 100644 --- a/docs/reference/cli/organizations_list.md +++ b/docs/reference/cli/organizations_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations list +description: List all organizations +--- + -# organizations list List all organizations diff --git a/docs/reference/cli/organizations_members.md b/docs/reference/cli/organizations_members.md index b71372f13b..7cb0c8db47 100644 --- a/docs/reference/cli/organizations_members.md +++ b/docs/reference/cli/organizations_members.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations members +description: Manage organization members +--- + -# organizations members Manage organization members diff --git a/docs/reference/cli/organizations_members_add.md b/docs/reference/cli/organizations_members_add.md index 57481f02dd..3bd1216662 100644 --- a/docs/reference/cli/organizations_members_add.md +++ b/docs/reference/cli/organizations_members_add.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations members add +description: Add a new member to the current organization +--- + -# organizations members add Add a new member to the current organization diff --git a/docs/reference/cli/organizations_members_edit-roles.md b/docs/reference/cli/organizations_members_edit-roles.md index 0d4a21a379..eabf57d6bb 100644 --- a/docs/reference/cli/organizations_members_edit-roles.md +++ b/docs/reference/cli/organizations_members_edit-roles.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations members edit-roles +description: "Edit organization member's roles" +--- + -# organizations members edit-roles Edit organization member's roles diff --git a/docs/reference/cli/organizations_members_list.md b/docs/reference/cli/organizations_members_list.md index 510a28e511..dc339704db 100644 --- a/docs/reference/cli/organizations_members_list.md +++ b/docs/reference/cli/organizations_members_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations members list +description: List all organization members +--- + -# organizations members list List all organization members diff --git a/docs/reference/cli/organizations_members_remove.md b/docs/reference/cli/organizations_members_remove.md index 9b6e294165..39b58e052b 100644 --- a/docs/reference/cli/organizations_members_remove.md +++ b/docs/reference/cli/organizations_members_remove.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations members remove +description: Remove a new member to the current organization +--- + -# organizations members remove Remove a new member to the current organization diff --git a/docs/reference/cli/organizations_roles.md b/docs/reference/cli/organizations_roles.md index bd91fc3085..ec42653b8f 100644 --- a/docs/reference/cli/organizations_roles.md +++ b/docs/reference/cli/organizations_roles.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations roles +description: Manage organization roles. +--- + -# organizations roles Manage organization roles. diff --git a/docs/reference/cli/organizations_roles_create.md b/docs/reference/cli/organizations_roles_create.md index 4a02babf36..36dc5eca8e 100644 --- a/docs/reference/cli/organizations_roles_create.md +++ b/docs/reference/cli/organizations_roles_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations roles create +description: Create a new organization custom role +--- + -# organizations roles create Create a new organization custom role diff --git a/docs/reference/cli/organizations_roles_show.md b/docs/reference/cli/organizations_roles_show.md index 1d5653839e..8bf9969599 100644 --- a/docs/reference/cli/organizations_roles_show.md +++ b/docs/reference/cli/organizations_roles_show.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations roles show +description: "Show role(s)" +--- + -# organizations roles show Show role(s) diff --git a/docs/reference/cli/organizations_roles_update.md b/docs/reference/cli/organizations_roles_update.md index 9637f19cd8..d323e622b5 100644 --- a/docs/reference/cli/organizations_roles_update.md +++ b/docs/reference/cli/organizations_roles_update.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations roles update +description: Update an organization custom role +--- + -# organizations roles update Update an organization custom role diff --git a/docs/reference/cli/organizations_settings.md b/docs/reference/cli/organizations_settings.md index 76a84135ed..8b278a4cd9 100644 --- a/docs/reference/cli/organizations_settings.md +++ b/docs/reference/cli/organizations_settings.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings +description: Manage organization settings. +--- + -# organizations settings Manage organization settings. diff --git a/docs/reference/cli/organizations_settings_set.md b/docs/reference/cli/organizations_settings_set.md index 97eb8007c3..ccf32ca0df 100644 --- a/docs/reference/cli/organizations_settings_set.md +++ b/docs/reference/cli/organizations_settings_set.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings set +description: Update specified organization setting. +--- + -# organizations settings set Update specified organization setting. diff --git a/docs/reference/cli/organizations_settings_set_group-sync.md b/docs/reference/cli/organizations_settings_set_group-sync.md index ceefa22a52..6a393933cb 100644 --- a/docs/reference/cli/organizations_settings_set_group-sync.md +++ b/docs/reference/cli/organizations_settings_set_group-sync.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings set group-sync +description: Group sync settings to sync groups from an IdP. +--- + -# organizations settings set group-sync Group sync settings to sync groups from an IdP. diff --git a/docs/reference/cli/organizations_settings_set_organization-sync.md b/docs/reference/cli/organizations_settings_set_organization-sync.md index 8580c6cef3..4443bf9974 100644 --- a/docs/reference/cli/organizations_settings_set_organization-sync.md +++ b/docs/reference/cli/organizations_settings_set_organization-sync.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings set organization-sync +description: Organization sync settings to sync organization memberships from an IdP. +--- + -# organizations settings set organization-sync Organization sync settings to sync organization memberships from an IdP. diff --git a/docs/reference/cli/organizations_settings_set_role-sync.md b/docs/reference/cli/organizations_settings_set_role-sync.md index 01d46319f5..92a359c3be 100644 --- a/docs/reference/cli/organizations_settings_set_role-sync.md +++ b/docs/reference/cli/organizations_settings_set_role-sync.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings set role-sync +description: Role sync settings to sync organization roles from an IdP. +--- + -# organizations settings set role-sync Role sync settings to sync organization roles from an IdP. diff --git a/docs/reference/cli/organizations_settings_set_workspace-sharing.md b/docs/reference/cli/organizations_settings_set_workspace-sharing.md index 579d2bbacd..58ff2d0c77 100644 --- a/docs/reference/cli/organizations_settings_set_workspace-sharing.md +++ b/docs/reference/cli/organizations_settings_set_workspace-sharing.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings set workspace-sharing +description: Workspace sharing settings for the organization. +--- + -# organizations settings set workspace-sharing Workspace sharing settings for the organization. diff --git a/docs/reference/cli/organizations_settings_show.md b/docs/reference/cli/organizations_settings_show.md index fdd3f00531..2dc033f5dc 100644 --- a/docs/reference/cli/organizations_settings_show.md +++ b/docs/reference/cli/organizations_settings_show.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings show +description: Outputs specified organization setting. +--- + -# organizations settings show Outputs specified organization setting. diff --git a/docs/reference/cli/organizations_settings_show_group-sync.md b/docs/reference/cli/organizations_settings_show_group-sync.md index 75a4398f88..080e02518e 100644 --- a/docs/reference/cli/organizations_settings_show_group-sync.md +++ b/docs/reference/cli/organizations_settings_show_group-sync.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings show group-sync +description: Group sync settings to sync groups from an IdP. +--- + -# organizations settings show group-sync Group sync settings to sync groups from an IdP. diff --git a/docs/reference/cli/organizations_settings_show_organization-sync.md b/docs/reference/cli/organizations_settings_show_organization-sync.md index 2054aa29b4..d677056ad3 100644 --- a/docs/reference/cli/organizations_settings_show_organization-sync.md +++ b/docs/reference/cli/organizations_settings_show_organization-sync.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings show organization-sync +description: Organization sync settings to sync organization memberships from an IdP. +--- + -# organizations settings show organization-sync Organization sync settings to sync organization memberships from an IdP. diff --git a/docs/reference/cli/organizations_settings_show_role-sync.md b/docs/reference/cli/organizations_settings_show_role-sync.md index 6fe2fd40a9..2f38a7a2a3 100644 --- a/docs/reference/cli/organizations_settings_show_role-sync.md +++ b/docs/reference/cli/organizations_settings_show_role-sync.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings show role-sync +description: Role sync settings to sync organization roles from an IdP. +--- + -# organizations settings show role-sync Role sync settings to sync organization roles from an IdP. diff --git a/docs/reference/cli/organizations_settings_show_workspace-sharing.md b/docs/reference/cli/organizations_settings_show_workspace-sharing.md index 9fbd7d1865..727a181e02 100644 --- a/docs/reference/cli/organizations_settings_show_workspace-sharing.md +++ b/docs/reference/cli/organizations_settings_show_workspace-sharing.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations settings show workspace-sharing +description: Workspace sharing settings for the organization. +--- + -# organizations settings show workspace-sharing Workspace sharing settings for the organization. diff --git a/docs/reference/cli/organizations_show.md b/docs/reference/cli/organizations_show.md index 90d5f00be1..0c6c46d921 100644 --- a/docs/reference/cli/organizations_show.md +++ b/docs/reference/cli/organizations_show.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: organizations show +description: "Show the organization. Using \"selected\" will show the selected organization from the \"--org\" flag. Using \"me\" will show all organizations you are a member of." +--- + -# organizations show Show the organization. Using "selected" will show the selected organization from the "--org" flag. Using "me" will show all organizations you are a member of. diff --git a/docs/reference/cli/ping.md b/docs/reference/cli/ping.md index 829f131818..b7efca5e06 100644 --- a/docs/reference/cli/ping.md +++ b/docs/reference/cli/ping.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ping +description: Ping a workspace +--- + -# ping Ping a workspace diff --git a/docs/reference/cli/port-forward.md b/docs/reference/cli/port-forward.md index 976b830fca..4319d1110b 100644 --- a/docs/reference/cli/port-forward.md +++ b/docs/reference/cli/port-forward.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: port-forward +description: "Forward ports from a workspace to the local machine. For reverse port forwarding, use \"coder ssh -R\"." +--- + -# port-forward Forward ports from a workspace to the local machine. For reverse port forwarding, use "coder ssh -R". diff --git a/docs/reference/cli/prebuilds.md b/docs/reference/cli/prebuilds.md index 90ee77dc91..4aa5763a7b 100644 --- a/docs/reference/cli/prebuilds.md +++ b/docs/reference/cli/prebuilds.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: prebuilds +description: Manage Coder prebuilds +--- + -# prebuilds Manage Coder prebuilds diff --git a/docs/reference/cli/prebuilds_pause.md b/docs/reference/cli/prebuilds_pause.md index 3aa8cf883a..96f3c95743 100644 --- a/docs/reference/cli/prebuilds_pause.md +++ b/docs/reference/cli/prebuilds_pause.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: prebuilds pause +description: Pause prebuilds +--- + -# prebuilds pause Pause prebuilds diff --git a/docs/reference/cli/prebuilds_resume.md b/docs/reference/cli/prebuilds_resume.md index 00e9dadc6c..c258bd919a 100644 --- a/docs/reference/cli/prebuilds_resume.md +++ b/docs/reference/cli/prebuilds_resume.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: prebuilds resume +description: Resume prebuilds +--- + -# prebuilds resume Resume prebuilds diff --git a/docs/reference/cli/provisioner.md b/docs/reference/cli/provisioner.md index 20acfd4fa5..0c7fcd9c6e 100644 --- a/docs/reference/cli/provisioner.md +++ b/docs/reference/cli/provisioner.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner +description: View and manage provisioner daemons and jobs +--- + -# provisioner View and manage provisioner daemons and jobs diff --git a/docs/reference/cli/provisioner_jobs.md b/docs/reference/cli/provisioner_jobs.md index 1bd2226af0..4d4193eddd 100644 --- a/docs/reference/cli/provisioner_jobs.md +++ b/docs/reference/cli/provisioner_jobs.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner jobs +description: View and manage provisioner jobs +--- + -# provisioner jobs View and manage provisioner jobs diff --git a/docs/reference/cli/provisioner_jobs_cancel.md b/docs/reference/cli/provisioner_jobs_cancel.md index 2040247b11..5ae522036f 100644 --- a/docs/reference/cli/provisioner_jobs_cancel.md +++ b/docs/reference/cli/provisioner_jobs_cancel.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner jobs cancel +description: Cancel a provisioner job +--- + -# provisioner jobs cancel Cancel a provisioner job diff --git a/docs/reference/cli/provisioner_jobs_list.md b/docs/reference/cli/provisioner_jobs_list.md index e845736890..93bb2c1c11 100644 --- a/docs/reference/cli/provisioner_jobs_list.md +++ b/docs/reference/cli/provisioner_jobs_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner jobs list +description: List provisioner jobs +--- + -# provisioner jobs list List provisioner jobs diff --git a/docs/reference/cli/provisioner_keys.md b/docs/reference/cli/provisioner_keys.md index 80cfd8f0a3..e886adf854 100644 --- a/docs/reference/cli/provisioner_keys.md +++ b/docs/reference/cli/provisioner_keys.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner keys +description: Manage provisioner keys +--- + -# provisioner keys Manage provisioner keys diff --git a/docs/reference/cli/provisioner_keys_create.md b/docs/reference/cli/provisioner_keys_create.md index 737ba187c9..784c7057f6 100644 --- a/docs/reference/cli/provisioner_keys_create.md +++ b/docs/reference/cli/provisioner_keys_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner keys create +description: Create a new provisioner key +--- + -# provisioner keys create Create a new provisioner key diff --git a/docs/reference/cli/provisioner_keys_delete.md b/docs/reference/cli/provisioner_keys_delete.md index cbbbbb90c7..eba3c6a403 100644 --- a/docs/reference/cli/provisioner_keys_delete.md +++ b/docs/reference/cli/provisioner_keys_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner keys delete +description: Delete a provisioner key +--- + -# provisioner keys delete Delete a provisioner key diff --git a/docs/reference/cli/provisioner_keys_list.md b/docs/reference/cli/provisioner_keys_list.md index 4f05a5e9b5..db8a2d6d10 100644 --- a/docs/reference/cli/provisioner_keys_list.md +++ b/docs/reference/cli/provisioner_keys_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner keys list +description: List provisioner keys in an organization +--- + -# provisioner keys list List provisioner keys in an organization diff --git a/docs/reference/cli/provisioner_list.md b/docs/reference/cli/provisioner_list.md index aa67dcd815..b9cf2c06ea 100644 --- a/docs/reference/cli/provisioner_list.md +++ b/docs/reference/cli/provisioner_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner list +description: List provisioner daemons in an organization +--- + -# provisioner list List provisioner daemons in an organization diff --git a/docs/reference/cli/provisioner_start.md b/docs/reference/cli/provisioner_start.md index f278bac310..1e1bb58ae3 100644 --- a/docs/reference/cli/provisioner_start.md +++ b/docs/reference/cli/provisioner_start.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: provisioner start +description: Run a provisioner daemon +--- + -# provisioner start Run a provisioner daemon diff --git a/docs/reference/cli/publickey.md b/docs/reference/cli/publickey.md index 557bdb7c9c..4a1b17060a 100644 --- a/docs/reference/cli/publickey.md +++ b/docs/reference/cli/publickey.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: publickey +description: Output your Coder public key used for Git operations +--- + -# publickey Output your Coder public key used for Git operations diff --git a/docs/reference/cli/rename.md b/docs/reference/cli/rename.md index 11ffae03b5..1ae0133c2c 100644 --- a/docs/reference/cli/rename.md +++ b/docs/reference/cli/rename.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: rename +description: Rename a workspace +--- + -# rename Rename a workspace diff --git a/docs/reference/cli/reset-password.md b/docs/reference/cli/reset-password.md index ada9ad7e7d..2a69dce4b6 100644 --- a/docs/reference/cli/reset-password.md +++ b/docs/reference/cli/reset-password.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: reset-password +description: "Directly connect to the database to reset a user's password" +--- + -# reset-password Directly connect to the database to reset a user's password diff --git a/docs/reference/cli/restart.md b/docs/reference/cli/restart.md index 526781f1ec..d55b3020d2 100644 --- a/docs/reference/cli/restart.md +++ b/docs/reference/cli/restart.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: restart +description: Restart a workspace +--- + -# restart Restart a workspace diff --git a/docs/reference/cli/schedule.md b/docs/reference/cli/schedule.md index c25bd4bf60..f4e8bfb267 100644 --- a/docs/reference/cli/schedule.md +++ b/docs/reference/cli/schedule.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: schedule +description: Schedule automated start and stop times for workspaces +--- + -# schedule Schedule automated start and stop times for workspaces diff --git a/docs/reference/cli/schedule_extend.md b/docs/reference/cli/schedule_extend.md index aa4540b4d7..6e91c9ceef 100644 --- a/docs/reference/cli/schedule_extend.md +++ b/docs/reference/cli/schedule_extend.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: schedule extend +description: Extend the stop time of a currently running workspace instance. +--- + -# schedule extend Extend the stop time of a currently running workspace instance. diff --git a/docs/reference/cli/schedule_show.md b/docs/reference/cli/schedule_show.md index 65d858c1fb..d4e0732836 100644 --- a/docs/reference/cli/schedule_show.md +++ b/docs/reference/cli/schedule_show.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: schedule show +description: Show workspace schedules +--- + -# schedule show Show workspace schedules diff --git a/docs/reference/cli/schedule_start.md b/docs/reference/cli/schedule_start.md index 886e5edf1a..66e70a6808 100644 --- a/docs/reference/cli/schedule_start.md +++ b/docs/reference/cli/schedule_start.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: schedule start +description: Edit workspace start schedule +--- + -# schedule start Edit workspace start schedule diff --git a/docs/reference/cli/schedule_stop.md b/docs/reference/cli/schedule_stop.md index a832c9c919..2a908b263d 100644 --- a/docs/reference/cli/schedule_stop.md +++ b/docs/reference/cli/schedule_stop.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: schedule stop +description: Edit workspace stop schedule +--- + -# schedule stop Edit workspace stop schedule diff --git a/docs/reference/cli/secret.md b/docs/reference/cli/secret.md index 1413650750..a8b64431ea 100644 --- a/docs/reference/cli/secret.md +++ b/docs/reference/cli/secret.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret +description: Manage secrets +--- + -# secret Manage secrets diff --git a/docs/reference/cli/secret_create.md b/docs/reference/cli/secret_create.md index 84e09ec294..9b4690e2e8 100644 --- a/docs/reference/cli/secret_create.md +++ b/docs/reference/cli/secret_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret create +description: Create a secret +--- + -# secret create Create a secret diff --git a/docs/reference/cli/secret_delete.md b/docs/reference/cli/secret_delete.md index bc493d907c..7a9bc4f389 100644 --- a/docs/reference/cli/secret_delete.md +++ b/docs/reference/cli/secret_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret delete +description: Delete a secret +--- + -# secret delete Delete a secret diff --git a/docs/reference/cli/secret_disable.md b/docs/reference/cli/secret_disable.md index 1ee4c3de82..a20fb258df 100644 --- a/docs/reference/cli/secret_disable.md +++ b/docs/reference/cli/secret_disable.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret disable +description: Disable a secret without removing it +--- + -# secret disable Disable a secret without removing it diff --git a/docs/reference/cli/secret_enable.md b/docs/reference/cli/secret_enable.md index 56d83a3867..82bc93bd5c 100644 --- a/docs/reference/cli/secret_enable.md +++ b/docs/reference/cli/secret_enable.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret enable +description: Enable a secret so it is injected into workspaces +--- + -# secret enable Enable a secret so it is injected into workspaces diff --git a/docs/reference/cli/secret_import.md b/docs/reference/cli/secret_import.md index 0c94b04d22..809803ad14 100644 --- a/docs/reference/cli/secret_import.md +++ b/docs/reference/cli/secret_import.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret import +description: Import secrets from a file +--- + -# secret import Import secrets from a file diff --git a/docs/reference/cli/secret_list.md b/docs/reference/cli/secret_list.md index 2a93cf659b..dfb758ac60 100644 --- a/docs/reference/cli/secret_list.md +++ b/docs/reference/cli/secret_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret list +description: "List secrets, or show one by name" +--- + -# secret list List secrets, or show one by name diff --git a/docs/reference/cli/secret_update.md b/docs/reference/cli/secret_update.md index fd628f03eb..c0485f9880 100644 --- a/docs/reference/cli/secret_update.md +++ b/docs/reference/cli/secret_update.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: secret update +description: Update a secret +--- + -# secret update Update a secret diff --git a/docs/reference/cli/server.md b/docs/reference/cli/server.md index 1ddd15dbdc..7840f2bd8b 100644 --- a/docs/reference/cli/server.md +++ b/docs/reference/cli/server.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server +description: Start a Coder server +--- + -# server Start a Coder server diff --git a/docs/reference/cli/server_create-admin-user.md b/docs/reference/cli/server_create-admin-user.md index 361465c896..2335e8b3ae 100644 --- a/docs/reference/cli/server_create-admin-user.md +++ b/docs/reference/cli/server_create-admin-user.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server create-admin-user +description: "Create a new admin user with the given username, email and password and adds it to every organization." +--- + -# server create-admin-user Create a new admin user with the given username, email and password and adds it to every organization. diff --git a/docs/reference/cli/server_dbcrypt.md b/docs/reference/cli/server_dbcrypt.md index f8d638a05a..5a51200a47 100644 --- a/docs/reference/cli/server_dbcrypt.md +++ b/docs/reference/cli/server_dbcrypt.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server dbcrypt +description: Manage database encryption. +--- + -# server dbcrypt Manage database encryption. diff --git a/docs/reference/cli/server_dbcrypt_decrypt.md b/docs/reference/cli/server_dbcrypt_decrypt.md index a7e05b7fdd..3dafbbcc52 100644 --- a/docs/reference/cli/server_dbcrypt_decrypt.md +++ b/docs/reference/cli/server_dbcrypt_decrypt.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server dbcrypt decrypt +description: Decrypt a previously encrypted database. +--- + -# server dbcrypt decrypt Decrypt a previously encrypted database. diff --git a/docs/reference/cli/server_dbcrypt_delete.md b/docs/reference/cli/server_dbcrypt_delete.md index 364386f2a8..28030aa680 100644 --- a/docs/reference/cli/server_dbcrypt_delete.md +++ b/docs/reference/cli/server_dbcrypt_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server dbcrypt delete +description: Delete all encrypted data from the database. THIS IS A DESTRUCTIVE OPERATION. +--- + -# server dbcrypt delete Delete all encrypted data from the database. THIS IS A DESTRUCTIVE OPERATION. diff --git a/docs/reference/cli/server_dbcrypt_rotate.md b/docs/reference/cli/server_dbcrypt_rotate.md index e2700c2631..8cb058299e 100644 --- a/docs/reference/cli/server_dbcrypt_rotate.md +++ b/docs/reference/cli/server_dbcrypt_rotate.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server dbcrypt rotate +description: Rotate database encryption keys. +--- + -# server dbcrypt rotate Rotate database encryption keys. diff --git a/docs/reference/cli/server_fix-oidc-links.md b/docs/reference/cli/server_fix-oidc-links.md index a79b701b0d..40e47404ba 100644 --- a/docs/reference/cli/server_fix-oidc-links.md +++ b/docs/reference/cli/server_fix-oidc-links.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server fix-oidc-links +description: "Reset OIDC linked IDs that do not match the expected issuer, allowing users to re-authenticate." +--- + -# server fix-oidc-links Reset OIDC linked IDs that do not match the expected issuer, allowing users to re-authenticate. diff --git a/docs/reference/cli/server_postgres-builtin-serve.md b/docs/reference/cli/server_postgres-builtin-serve.md index 55d8ad2a8d..c5f25976b2 100644 --- a/docs/reference/cli/server_postgres-builtin-serve.md +++ b/docs/reference/cli/server_postgres-builtin-serve.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server postgres-builtin-serve +description: Run the built-in PostgreSQL deployment. +--- + -# server postgres-builtin-serve Run the built-in PostgreSQL deployment. diff --git a/docs/reference/cli/server_postgres-builtin-url.md b/docs/reference/cli/server_postgres-builtin-url.md index f8fdebb042..52e5509055 100644 --- a/docs/reference/cli/server_postgres-builtin-url.md +++ b/docs/reference/cli/server_postgres-builtin-url.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: server postgres-builtin-url +description: Output the connection URL for the built-in PostgreSQL deployment. +--- + -# server postgres-builtin-url Output the connection URL for the built-in PostgreSQL deployment. diff --git a/docs/reference/cli/show.md b/docs/reference/cli/show.md index c6fb9a2c81..70c168ca96 100644 --- a/docs/reference/cli/show.md +++ b/docs/reference/cli/show.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: show +description: "Display details of a workspace's resources and agents" +--- + -# show Display details of a workspace's resources and agents diff --git a/docs/reference/cli/speedtest.md b/docs/reference/cli/speedtest.md index d17125ad2a..f20ecdf699 100644 --- a/docs/reference/cli/speedtest.md +++ b/docs/reference/cli/speedtest.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: speedtest +description: Run upload and download tests from your machine to a workspace +--- + -# speedtest Run upload and download tests from your machine to a workspace diff --git a/docs/reference/cli/ssh.md b/docs/reference/cli/ssh.md index 4f5ec13177..fc9790f83b 100644 --- a/docs/reference/cli/ssh.md +++ b/docs/reference/cli/ssh.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: ssh +description: Start a shell into a workspace or run a command +--- + -# ssh Start a shell into a workspace or run a command diff --git a/docs/reference/cli/start.md b/docs/reference/cli/start.md index a228282948..de7d9c882a 100644 --- a/docs/reference/cli/start.md +++ b/docs/reference/cli/start.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: start +description: Start a workspace +--- + -# start Start a workspace diff --git a/docs/reference/cli/stat.md b/docs/reference/cli/stat.md index c84c56ee5a..b28a29d208 100644 --- a/docs/reference/cli/stat.md +++ b/docs/reference/cli/stat.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: stat +description: Show resource usage for the current workspace. +--- + -# stat Show resource usage for the current workspace. diff --git a/docs/reference/cli/stat_cpu.md b/docs/reference/cli/stat_cpu.md index c7013e1683..a14844f59c 100644 --- a/docs/reference/cli/stat_cpu.md +++ b/docs/reference/cli/stat_cpu.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: stat cpu +description: "Show CPU usage, in cores." +--- + -# stat cpu Show CPU usage, in cores. diff --git a/docs/reference/cli/stat_disk.md b/docs/reference/cli/stat_disk.md index 4cf80f6075..06d6fab19f 100644 --- a/docs/reference/cli/stat_disk.md +++ b/docs/reference/cli/stat_disk.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: stat disk +description: "Show disk usage, in gigabytes." +--- + -# stat disk Show disk usage, in gigabytes. diff --git a/docs/reference/cli/stat_mem.md b/docs/reference/cli/stat_mem.md index d69ba19ee8..04c8c65c99 100644 --- a/docs/reference/cli/stat_mem.md +++ b/docs/reference/cli/stat_mem.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: stat mem +description: "Show memory usage, in gigabytes." +--- + -# stat mem Show memory usage, in gigabytes. diff --git a/docs/reference/cli/state.md b/docs/reference/cli/state.md index ebac28a646..80c28d4e79 100644 --- a/docs/reference/cli/state.md +++ b/docs/reference/cli/state.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: state +description: Manually manage Terraform state to fix broken workspaces +--- + -# state Manually manage Terraform state to fix broken workspaces diff --git a/docs/reference/cli/state_pull.md b/docs/reference/cli/state_pull.md index 089548ab93..50ec4778bb 100644 --- a/docs/reference/cli/state_pull.md +++ b/docs/reference/cli/state_pull.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: state pull +description: Pull a Terraform state file from a workspace. +--- + -# state pull Pull a Terraform state file from a workspace. diff --git a/docs/reference/cli/state_push.md b/docs/reference/cli/state_push.md index 7796d0ba8d..620cea403e 100644 --- a/docs/reference/cli/state_push.md +++ b/docs/reference/cli/state_push.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: state push +description: Push a Terraform state file to a workspace. +--- + -# state push Push a Terraform state file to a workspace. diff --git a/docs/reference/cli/stop.md b/docs/reference/cli/stop.md index a442448de4..b07283846f 100644 --- a/docs/reference/cli/stop.md +++ b/docs/reference/cli/stop.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: stop +description: Stop a workspace +--- + -# stop Stop a workspace diff --git a/docs/reference/cli/support.md b/docs/reference/cli/support.md index b530264f36..cc07633b2e 100644 --- a/docs/reference/cli/support.md +++ b/docs/reference/cli/support.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: support +description: Commands for troubleshooting issues with a Coder deployment. +--- + -# support Commands for troubleshooting issues with a Coder deployment. diff --git a/docs/reference/cli/support_bundle.md b/docs/reference/cli/support_bundle.md index 5854dafccd..2b03067543 100644 --- a/docs/reference/cli/support_bundle.md +++ b/docs/reference/cli/support_bundle.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: support bundle +description: Generate a support bundle to troubleshoot issues connecting to a workspace. +--- + -# support bundle Generate a support bundle to troubleshoot issues connecting to a workspace. diff --git a/docs/reference/cli/task.md b/docs/reference/cli/task.md index 518ed4dd1f..433fba5191 100644 --- a/docs/reference/cli/task.md +++ b/docs/reference/cli/task.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task +description: Manage tasks +--- + -# task Manage tasks diff --git a/docs/reference/cli/task_create.md b/docs/reference/cli/task_create.md index 726c805469..f230208c01 100644 --- a/docs/reference/cli/task_create.md +++ b/docs/reference/cli/task_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task create +description: Create a task +--- + -# task create Create a task diff --git a/docs/reference/cli/task_delete.md b/docs/reference/cli/task_delete.md index 2ab3e90b30..761d1e4bd9 100644 --- a/docs/reference/cli/task_delete.md +++ b/docs/reference/cli/task_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task delete +description: Delete tasks +--- + -# task delete Delete tasks diff --git a/docs/reference/cli/task_list.md b/docs/reference/cli/task_list.md index 1a9335f65f..44043646f6 100644 --- a/docs/reference/cli/task_list.md +++ b/docs/reference/cli/task_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task list +description: List tasks +--- + -# task list List tasks diff --git a/docs/reference/cli/task_logs.md b/docs/reference/cli/task_logs.md index d7e4b0eda6..d3f026a55a 100644 --- a/docs/reference/cli/task_logs.md +++ b/docs/reference/cli/task_logs.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task logs +description: "Show a task's logs" +--- + -# task logs Show a task's logs diff --git a/docs/reference/cli/task_pause.md b/docs/reference/cli/task_pause.md index 34c14199e1..caf3d8e2b9 100644 --- a/docs/reference/cli/task_pause.md +++ b/docs/reference/cli/task_pause.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task pause +description: Pause a task +--- + -# task pause Pause a task diff --git a/docs/reference/cli/task_resume.md b/docs/reference/cli/task_resume.md index 1723a01678..620699eeb3 100644 --- a/docs/reference/cli/task_resume.md +++ b/docs/reference/cli/task_resume.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task resume +description: Resume a task +--- + -# task resume Resume a task diff --git a/docs/reference/cli/task_send.md b/docs/reference/cli/task_send.md index 914d66daaf..a3ccfcd919 100644 --- a/docs/reference/cli/task_send.md +++ b/docs/reference/cli/task_send.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task send +description: Send input to a task +--- + -# task send Send input to a task diff --git a/docs/reference/cli/task_status.md b/docs/reference/cli/task_status.md index 4a167a249f..d8cf2d7b99 100644 --- a/docs/reference/cli/task_status.md +++ b/docs/reference/cli/task_status.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: task status +description: Show the status of a task. +--- + -# task status Show the status of a task. diff --git a/docs/reference/cli/templates.md b/docs/reference/cli/templates.md index e1141f5db8..8ebaac9e16 100644 --- a/docs/reference/cli/templates.md +++ b/docs/reference/cli/templates.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates +description: Manage templates +--- + -# templates Manage templates diff --git a/docs/reference/cli/templates_archive.md b/docs/reference/cli/templates_archive.md index 648568c9fe..00b21fb85d 100644 --- a/docs/reference/cli/templates_archive.md +++ b/docs/reference/cli/templates_archive.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates archive +description: "Archive unused or failed template versions from a given template(s)" +--- + -# templates archive Archive unused or failed template versions from a given template(s) diff --git a/docs/reference/cli/templates_create.md b/docs/reference/cli/templates_create.md index a3bba84d92..1d9d26a922 100644 --- a/docs/reference/cli/templates_create.md +++ b/docs/reference/cli/templates_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates create +description: "DEPRECATED: Create a template from the current directory or as specified by flag" +--- + -# templates create DEPRECATED: Create a template from the current directory or as specified by flag diff --git a/docs/reference/cli/templates_delete.md b/docs/reference/cli/templates_delete.md index 45b15c5dcc..2467b55de9 100644 --- a/docs/reference/cli/templates_delete.md +++ b/docs/reference/cli/templates_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates delete +description: Delete templates +--- + -# templates delete Delete templates diff --git a/docs/reference/cli/templates_edit.md b/docs/reference/cli/templates_edit.md index 2e472d1600..d294b5e1fc 100644 --- a/docs/reference/cli/templates_edit.md +++ b/docs/reference/cli/templates_edit.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates edit +description: Edit the metadata of a template by name. +--- + -# templates edit Edit the metadata of a template by name. diff --git a/docs/reference/cli/templates_init.md b/docs/reference/cli/templates_init.md index cc617fe9cc..7c6abf09c0 100644 --- a/docs/reference/cli/templates_init.md +++ b/docs/reference/cli/templates_init.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates init +description: Get started with a templated template. +--- + -# templates init Get started with a templated template. diff --git a/docs/reference/cli/templates_list.md b/docs/reference/cli/templates_list.md index d5ec9d3cea..0f74cc4e6e 100644 --- a/docs/reference/cli/templates_list.md +++ b/docs/reference/cli/templates_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates list +description: List all the templates available for the organization +--- + -# templates list List all the templates available for the organization diff --git a/docs/reference/cli/templates_presets.md b/docs/reference/cli/templates_presets.md index a03f206366..327162f3d6 100644 --- a/docs/reference/cli/templates_presets.md +++ b/docs/reference/cli/templates_presets.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates presets +description: Manage presets of the specified template +--- + -# templates presets Manage presets of the specified template diff --git a/docs/reference/cli/templates_presets_list.md b/docs/reference/cli/templates_presets_list.md index 5c2d26859f..0f2ecd3ff8 100644 --- a/docs/reference/cli/templates_presets_list.md +++ b/docs/reference/cli/templates_presets_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates presets list +description: List all presets of the specified template. Defaults to the active template version. +--- + -# templates presets list List all presets of the specified template. Defaults to the active template version. diff --git a/docs/reference/cli/templates_pull.md b/docs/reference/cli/templates_pull.md index a5a4731807..e0d6d88ec9 100644 --- a/docs/reference/cli/templates_pull.md +++ b/docs/reference/cli/templates_pull.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates pull +description: "Download the active, latest, or specified version of a template to a path." +--- + -# templates pull Download the active, latest, or specified version of a template to a path. diff --git a/docs/reference/cli/templates_push.md b/docs/reference/cli/templates_push.md index c27442f4f5..681ed7c8d4 100644 --- a/docs/reference/cli/templates_push.md +++ b/docs/reference/cli/templates_push.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates push +description: Create or update a template from the current directory or as specified by flag +--- + -# templates push Create or update a template from the current directory or as specified by flag diff --git a/docs/reference/cli/templates_versions.md b/docs/reference/cli/templates_versions.md index 8eb927967d..099a48366e 100644 --- a/docs/reference/cli/templates_versions.md +++ b/docs/reference/cli/templates_versions.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates versions +description: Manage different versions of the specified template +--- + -# templates versions Manage different versions of the specified template diff --git a/docs/reference/cli/templates_versions_archive.md b/docs/reference/cli/templates_versions_archive.md index e4da6c4340..e216ce6c42 100644 --- a/docs/reference/cli/templates_versions_archive.md +++ b/docs/reference/cli/templates_versions_archive.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates versions archive +description: "Archive a template version(s)." +--- + -# templates versions archive Archive a template version(s). diff --git a/docs/reference/cli/templates_versions_list.md b/docs/reference/cli/templates_versions_list.md index 25c82af95d..31039279a4 100644 --- a/docs/reference/cli/templates_versions_list.md +++ b/docs/reference/cli/templates_versions_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates versions list +description: List all the versions of the specified template +--- + -# templates versions list List all the versions of the specified template diff --git a/docs/reference/cli/templates_versions_promote.md b/docs/reference/cli/templates_versions_promote.md index ecf3ab661c..6e6ef6d216 100644 --- a/docs/reference/cli/templates_versions_promote.md +++ b/docs/reference/cli/templates_versions_promote.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates versions promote +description: Promote a template version to active. +--- + -# templates versions promote Promote a template version to active. diff --git a/docs/reference/cli/templates_versions_unarchive.md b/docs/reference/cli/templates_versions_unarchive.md index 5013bda71a..8919dded8d 100644 --- a/docs/reference/cli/templates_versions_unarchive.md +++ b/docs/reference/cli/templates_versions_unarchive.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: templates versions unarchive +description: "Unarchive a template version(s)." +--- + -# templates versions unarchive Unarchive a template version(s). diff --git a/docs/reference/cli/tokens.md b/docs/reference/cli/tokens.md index 687b90b3e3..ddd1f5d293 100644 --- a/docs/reference/cli/tokens.md +++ b/docs/reference/cli/tokens.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: tokens +description: Manage personal access tokens +--- + -# tokens Manage personal access tokens diff --git a/docs/reference/cli/tokens_create.md b/docs/reference/cli/tokens_create.md index 56873aaec7..6800e1ceca 100644 --- a/docs/reference/cli/tokens_create.md +++ b/docs/reference/cli/tokens_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: tokens create +description: Create a token +--- + -# tokens create Create a token diff --git a/docs/reference/cli/tokens_list.md b/docs/reference/cli/tokens_list.md index 273901870b..b4860a2a0a 100644 --- a/docs/reference/cli/tokens_list.md +++ b/docs/reference/cli/tokens_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: tokens list +description: List tokens +--- + -# tokens list List tokens diff --git a/docs/reference/cli/tokens_remove.md b/docs/reference/cli/tokens_remove.md index 8083cfa1f1..a8b2c7f486 100644 --- a/docs/reference/cli/tokens_remove.md +++ b/docs/reference/cli/tokens_remove.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: tokens remove +description: Expire or delete a token +--- + -# tokens remove Expire or delete a token diff --git a/docs/reference/cli/tokens_view.md b/docs/reference/cli/tokens_view.md index f5008f5e41..80cbd61c4e 100644 --- a/docs/reference/cli/tokens_view.md +++ b/docs/reference/cli/tokens_view.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: tokens view +description: Display detailed information about a token +--- + -# tokens view Display detailed information about a token diff --git a/docs/reference/cli/unfavorite.md b/docs/reference/cli/unfavorite.md index 2bf15b437e..5ea98588d7 100644 --- a/docs/reference/cli/unfavorite.md +++ b/docs/reference/cli/unfavorite.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: unfavorite +description: Remove a workspace from your favorites +--- + -# unfavorite Remove a workspace from your favorites diff --git a/docs/reference/cli/update.md b/docs/reference/cli/update.md index be73c0e126..efa9929651 100644 --- a/docs/reference/cli/update.md +++ b/docs/reference/cli/update.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: update +description: "Will update and start a given workspace if it is out of date. If the workspace is already running, it will be stopped first." +--- + -# update Will update and start a given workspace if it is out of date. If the workspace is already running, it will be stopped first. diff --git a/docs/reference/cli/users.md b/docs/reference/cli/users.md index 96e6d43335..85fd86c4a4 100644 --- a/docs/reference/cli/users.md +++ b/docs/reference/cli/users.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users +description: Manage users +--- + -# users Manage users diff --git a/docs/reference/cli/users_activate.md b/docs/reference/cli/users_activate.md index e82313c0c8..ebee012268 100644 --- a/docs/reference/cli/users_activate.md +++ b/docs/reference/cli/users_activate.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users activate +description: "Update a user's status to 'active'. Active users can fully interact with the platform" +--- + -# users activate Update a user's status to 'active'. Active users can fully interact with the platform diff --git a/docs/reference/cli/users_create.md b/docs/reference/cli/users_create.md index 4640b1d18d..fa7560085f 100644 --- a/docs/reference/cli/users_create.md +++ b/docs/reference/cli/users_create.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users create +description: Create a new user. +--- + -# users create Create a new user. diff --git a/docs/reference/cli/users_delete.md b/docs/reference/cli/users_delete.md index 7bfe7db59c..6b890c3967 100644 --- a/docs/reference/cli/users_delete.md +++ b/docs/reference/cli/users_delete.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users delete +description: Delete a user by username or user_id. +--- + -# users delete Delete a user by username or user_id. diff --git a/docs/reference/cli/users_edit-roles.md b/docs/reference/cli/users_edit-roles.md index 2dda192e43..47383add42 100644 --- a/docs/reference/cli/users_edit-roles.md +++ b/docs/reference/cli/users_edit-roles.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users edit-roles +description: "Edit a user's roles by username or id" +--- + -# users edit-roles Edit a user's roles by username or id diff --git a/docs/reference/cli/users_list.md b/docs/reference/cli/users_list.md index 7217a8267b..a9e2955098 100644 --- a/docs/reference/cli/users_list.md +++ b/docs/reference/cli/users_list.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users list +description: Prints the list of users. +--- + -# users list Prints the list of users. diff --git a/docs/reference/cli/users_oidc-claims.md b/docs/reference/cli/users_oidc-claims.md index a38471b118..396e2f76f4 100644 --- a/docs/reference/cli/users_oidc-claims.md +++ b/docs/reference/cli/users_oidc-claims.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users oidc-claims +description: Display the OIDC claims for the authenticated user. +--- + -# users oidc-claims Display the OIDC claims for the authenticated user. diff --git a/docs/reference/cli/users_show.md b/docs/reference/cli/users_show.md index de53d67384..f4b92ac594 100644 --- a/docs/reference/cli/users_show.md +++ b/docs/reference/cli/users_show.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users show +description: "Show a single user. Use 'me' to indicate the currently authenticated user." +--- + -# users show Show a single user. Use 'me' to indicate the currently authenticated user. diff --git a/docs/reference/cli/users_suspend.md b/docs/reference/cli/users_suspend.md index 286a73cd24..efb26bd148 100644 --- a/docs/reference/cli/users_suspend.md +++ b/docs/reference/cli/users_suspend.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: users suspend +description: "Update a user's status to 'suspended'. A suspended user cannot log into the platform" +--- + -# users suspend Update a user's status to 'suspended'. A suspended user cannot log into the platform diff --git a/docs/reference/cli/version.md b/docs/reference/cli/version.md index cb0573c597..19ff4808e7 100644 --- a/docs/reference/cli/version.md +++ b/docs/reference/cli/version.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: version +description: Show coder version +--- + -# version Show coder version diff --git a/docs/reference/cli/whoami.md b/docs/reference/cli/whoami.md index 9fb9f303c9..d1db41b119 100644 --- a/docs/reference/cli/whoami.md +++ b/docs/reference/cli/whoami.md @@ -1,5 +1,10 @@ +--- +# Code generated by make gen. DO NOT EDIT. +title: whoami +description: Fetch authenticated user info for Coder deployment +--- + -# whoami Fetch authenticated user info for Coder deployment diff --git a/docs/support/support-bundle.md b/docs/support/support-bundle.md index 6d79e11c3a..4d7e2750ea 100644 --- a/docs/support/support-bundle.md +++ b/docs/support/support-bundle.md @@ -70,7 +70,7 @@ A brief overview of all files contained in the bundle is provided below: > It is recommended to generate a support bundle from a location > experiencing workspace connectivity issues. -3. Ensure you are [logged in](../reference/cli/login.md#login) to your Coder +3. Ensure you are [logged in](../reference/cli/login.md) to your Coder deployment. Any authenticated user can generate a support bundle. Users with the Owner role will get the most complete bundle; non-admin users will still get a useful bundle but some admin-only data will be omitted (see the note diff --git a/scripts/apidocgen/postprocess/main.go b/scripts/apidocgen/postprocess/main.go index 95592c8b25..1cfbfd1e4f 100644 --- a/scripts/apidocgen/postprocess/main.go +++ b/scripts/apidocgen/postprocess/main.go @@ -16,14 +16,17 @@ import ( "golang.org/x/xerrors" "github.com/coder/coder/v2/scripts/atomicwrite" + "github.com/coder/coder/v2/scripts/docgenenv" ) const ( - apiSubdir = "reference/api" - apiIndexFile = "index.md" - apiIndexContent = `# API - -Get started with the Coder API: + apiSubdir = "reference/api" + apiIndexFile = "index.md" + // apiIndexBody is the index page content below its front matter and the + // generated-content banner. The front matter is generated from the "REST + // API" manifest route (see writeDocs) so the index mirrors the manifest like + // every other generated page. + apiIndexBody = `Get started with the Coder API: ## Quickstart @@ -128,9 +131,37 @@ func prepareDocsDirectory() error { func writeDocs(sections [][]byte) error { log.Println("Write docs to destination") - apiDir := path.Join(docsDirectory, apiSubdir) - err := atomicwrite.File(path.Join(apiDir, apiIndexFile), []byte(apiIndexContent)) + manifestPath := path.Join(docsDirectory, "manifest.json") + m, err := docgenenv.LoadManifest(manifestPath) if err != nil { + return err + } + + // Resolve the REST API route once. Both the page front matter and the + // regenerated manifest routes read from this single traversal, so the + // metadata source and the rewrite target can't drift apart. + restAPI := m.FindRoute("Reference", "REST API") + if restAPI == nil { + return xerrors.Errorf("could not find REST API route in manifest %q", manifestPath) + } + + // Index existing REST API child routes by title so their curated metadata + // (description, state, icon_path) flows into both the page front matter and + // the regenerated manifest routes. + existingByTitle := make(map[string]docgenenv.Route) + for _, child := range restAPI.Children { + existingByTitle[child.Title] = child + } + + apiDir := path.Join(docsDirectory, apiSubdir) + + // The index page mirrors the "REST API" route's own curated metadata + // (title/description/icon_path) rather than a hardcoded title, so its front + // matter matches the manifest like every other generated page. + indexRoute := *restAPI + indexRoute.Children = nil + indexContent := append([]byte(docgenenv.GeneratedHeader(indexRoute)), []byte(apiIndexBody)...) + if err := atomicwrite.File(path.Join(apiDir, apiIndexFile), indexContent); err != nil { return xerrors.Errorf(`can't write the index file: %w`, err) } @@ -140,7 +171,7 @@ func writeDocs(sections [][]byte) error { } var mdFiles []mdFile - // Write .md files for grouped API method (Templates, Workspaces, etc.) + // Write .md files for grouped API methods (Templates, Workspaces, etc.) for _, section := range sections { sectionName, err := extractSectionName(section) if err != nil { @@ -148,10 +179,13 @@ func writeDocs(sections [][]byte) error { } log.Printf("Write section: %s", sectionName) + // Carry the manifest route's curated metadata into the front matter. + r := existingByTitle[sectionName] + r.Title = sectionName + mdFilename := toMdFilename(sectionName) docPath := path.Join(apiDir, mdFilename) - err = atomicwrite.File(docPath, section) - if err != nil { + if err := atomicwrite.File(docPath, prependGeneratedHeader(section, r)); err != nil { return xerrors.Errorf(`can't write doc file "%s": %w`, docPath, err) } mdFiles = append(mdFiles, mdFile{ @@ -172,78 +206,31 @@ func writeDocs(sections [][]byte) error { return slices.IsSorted([]string{mdFiles[i].title, mdFiles[j].title}) }) - // Update manifest.json - type route struct { - Title string `json:"title,omitempty"` - Description string `json:"description,omitempty"` - Path string `json:"path,omitempty"` - IconPath string `json:"icon_path,omitempty"` - State []string `json:"state,omitempty"` - Children []route `json:"children,omitempty"` - } - - type manifest struct { - Versions []string `json:"versions,omitempty"` - Routes []route `json:"routes,omitempty"` - } - - manifestPath := path.Join(docsDirectory, "manifest.json") - manifestFile, err := os.ReadFile(manifestPath) - if err != nil { - return xerrors.Errorf("can't read manifest file: %w", err) - } - log.Printf("Read manifest file: %dB", len(manifestFile)) - - var m manifest - err = json.Unmarshal(manifestFile, &m) - if err != nil { - return xerrors.Errorf("json.Unmarshal failed: %w", err) - } - - for i, r := range m.Routes { - if r.Title != "Reference" { - continue + // Update manifest.json. Generated routes overwrite Title and Path; + // existing state/description/icon_path are preserved (keyed by title) so + // callouts like `state: ["experimental"]` survive regeneration. restAPI + // aliases m, so replacing its children updates the manifest in place. + var children []docgenenv.Route + for _, mdf := range mdFiles { + docRoute := docgenenv.Route{ + Title: mdf.title, + Path: mdf.path, } - for j, child := range r.Children { - if child.Title != "REST API" { - continue - } - - // Preserve existing state and description on children, keyed by - // title, so that callouts like `state: ["experimental"]` survive - // regeneration. Generated routes always overwrite Title and Path. - existingByTitle := make(map[string]route, len(child.Children)) - for _, existing := range child.Children { - existingByTitle[existing.Title] = existing - } - - var children []route - for _, mdf := range mdFiles { - docRoute := route{ - Title: mdf.title, - Path: mdf.path, - } - if existing, ok := existingByTitle[mdf.title]; ok { - docRoute.State = existing.State - docRoute.Description = existing.Description - docRoute.IconPath = existing.IconPath - } - children = append(children, docRoute) - } - - m.Routes[i].Children[j].Children = children - break + if existing, ok := existingByTitle[mdf.title]; ok { + docRoute.State = existing.State + docRoute.Description = existing.Description + docRoute.IconPath = existing.IconPath } - break + children = append(children, docRoute) } + restAPI.Children = children - manifestFile, err = json.MarshalIndent(m, "", " ") + manifestFile, err := json.MarshalIndent(m, "", " ") if err != nil { return xerrors.Errorf("json.Marshal failed: %w", err) } - err = atomicwrite.File(manifestPath, manifestFile) - if err != nil { + if err := atomicwrite.File(manifestPath, manifestFile); err != nil { return xerrors.Errorf("can't write manifest file: %w", err) } log.Printf("Write manifest file: %dB", len(manifestFile)) @@ -253,13 +240,43 @@ func writeDocs(sections [][]byte) error { func extractSectionName(section []byte) (string, error) { scanner := bufio.NewScanner(bytes.NewReader(section)) if !scanner.Scan() { + // Scan returns false on EOF or error. A first line past + // bufio.Scanner's token limit surfaces only in Err(); report it as a + // scanning error rather than mislabeling it a missing header. + if err := scanner.Err(); err != nil { + return "", xerrors.Errorf("scanning section: %w", err) + } return "", xerrors.Errorf("section header was expected") } - header := scanner.Text()[2:] // Skip # - return strings.TrimSpace(header), nil + header := scanner.Text() + name, ok := strings.CutPrefix(header, "# ") + if !ok { + return "", xerrors.Errorf("section header %q must start with %q", header, "# ") + } + return strings.TrimSpace(name), nil } func toMdFilename(sectionName string) string { return nonAlphanumericRegex.ReplaceAllLiteralString(strings.ReplaceAll(strings.ToLower(sectionName), " ", ""), "-") + ".md" } + +// prependGeneratedHeader replaces the leading "# {name}" heading of a raw API +// section with r's generated-page header (front matter plus the shared +// generated-content banner). Callers pass sections that have already cleared +// extractSectionName, whose fail-fast on a missing "# " heading is the +// load-bearing guarantee. The prefix check here is a defensive backstop: if a +// section without the heading ever reached this function, it keeps the body +// intact instead of dropping the first real content line. +func prependGeneratedHeader(section []byte, r docgenenv.Route) []byte { + body := section + if bytes.HasPrefix(section, []byte("# ")) { + if _, rest, found := bytes.Cut(section, []byte{'\n'}); found { + body = rest + } else { + body = nil + } + } + body = bytes.TrimLeft(body, "\r\n") + return append([]byte(docgenenv.GeneratedHeader(r)), body...) +} diff --git a/scripts/apidocgen/postprocess/main_test.go b/scripts/apidocgen/postprocess/main_test.go new file mode 100644 index 0000000000..e7b4ef9d23 --- /dev/null +++ b/scripts/apidocgen/postprocess/main_test.go @@ -0,0 +1,95 @@ +package main + +import ( + "bufio" + "strings" + "testing" + + "github.com/stretchr/testify/require" + + "github.com/coder/coder/v2/scripts/docgenenv" +) + +func TestPrependGeneratedHeader(t *testing.T) { + t.Parallel() + + section := []byte("# Templates\n\nThe body.\n") + got := string(prependGeneratedHeader(section, docgenenv.Route{ + Title: "Templates", + Description: "Manage templates", + })) + want := "---\n" + + "# Code generated by make gen. DO NOT EDIT.\n" + + "title: Templates\n" + + "description: Manage templates\n" + + "---\n\n" + + "\n\n" + + "The body.\n" + require.Equal(t, want, got) +} + +// TestPrependGeneratedHeaderStateAndQuoting covers the curated-metadata path: a +// description with characters YAML would misparse is quoted, and state renders +// as a YAML sequence. +func TestPrependGeneratedHeaderStateAndQuoting(t *testing.T) { + t.Parallel() + + section := []byte("# Chats\nBody starts immediately.\n") + got := string(prependGeneratedHeader(section, docgenenv.Route{ + Title: "Chats", + Description: "REST endpoints for Coder Agents Chats API (programmatic agent sessions).", + State: []string{"early access"}, + })) + want := "---\n" + + "# Code generated by make gen. DO NOT EDIT.\n" + + "title: Chats\n" + + `description: "REST endpoints for Coder Agents Chats API (programmatic agent sessions)."` + "\n" + + "state:\n" + + " - early access\n" + + "---\n\n" + + "\n\n" + + "Body starts immediately.\n" + require.Equal(t, want, got) +} + +// TestPrependGeneratedHeaderKeepsBodyWithoutHeading verifies the guard: when the +// first line is not the "# {name}" heading, the whole section is preserved +// rather than silently dropping the first content line. +func TestPrependGeneratedHeaderKeepsBodyWithoutHeading(t *testing.T) { + t.Parallel() + + section := []byte("No heading here.\nSecond line.\n") + got := string(prependGeneratedHeader(section, docgenenv.Route{Title: "General"})) + want := "---\n" + + "# Code generated by make gen. DO NOT EDIT.\n" + + "title: General\n" + + "---\n\n" + + "\n\n" + + "No heading here.\nSecond line.\n" + require.Equal(t, want, got) +} + +// TestExtractSectionName covers extractSectionName's contract, the load-bearing +// guard prependFrontMatter relies on: the first line must be a "# {name}" +// heading, and a section without one (or an empty section) is rejected, not +// sliced into a bogus name. +func TestExtractSectionName(t *testing.T) { + t.Parallel() + + name, err := extractSectionName([]byte("# Templates\n\nBody.\n")) + require.NoError(t, err) + require.Equal(t, "Templates", name) + + _, err = extractSectionName([]byte("Body without a heading.\n")) + require.Error(t, err) + + _, err = extractSectionName(nil) + require.Error(t, err) + + // A first line past bufio.Scanner's token limit makes Scan return false + // with the reason only in Err(); surface it as a scanning error instead of + // a missing-header error. + _, err = extractSectionName([]byte(strings.Repeat("a", bufio.MaxScanTokenSize+1))) + require.Error(t, err) + require.Contains(t, err.Error(), "scanning section") +} diff --git a/scripts/clidocgen/command.tpl b/scripts/clidocgen/command.tpl index 1f2a4a0b97..c2ced269c7 100644 --- a/scripts/clidocgen/command.tpl +++ b/scripts/clidocgen/command.tpl @@ -1,5 +1,5 @@ - -# {{ fullName . }} +{{- frontMatter . -}} +{{ generatedContentBanner }} {{ with .Short }} {{ . }} diff --git a/scripts/clidocgen/gen.go b/scripts/clidocgen/gen.go index dde21ef78c..fa30bdadcf 100644 --- a/scripts/clidocgen/gen.go +++ b/scripts/clidocgen/gen.go @@ -13,6 +13,7 @@ import ( "github.com/coder/coder/v2/buildinfo" "github.com/coder/coder/v2/scripts/atomicwrite" + "github.com/coder/coder/v2/scripts/docgenenv" "github.com/coder/flog" "github.com/coder/serpent" ) @@ -50,9 +51,6 @@ func init() { } return visible }, - "atRoot": func(cmd *serpent.Command) bool { - return cmd.FullName() == "coder" - }, "newLinesToBr": func(s string) string { return strings.ReplaceAll(s, "\n", "
") }, @@ -60,7 +58,24 @@ func init() { return fmt.Sprintf("%s", s) }, "commandURI": fmtDocFilename, - "fullName": fullName, + // frontMatter renders the page's YAML front matter through the + // shared docgenenv emitter, so the CLI and API generators cannot + // drift on field set, ordering, or escaping. The CLI index mirrors + // the "Command Line" manifest route (main populates cliIndexRoute + // before the template runs); every other page uses the command's + // own name and short description. + "frontMatter": func(cmd *serpent.Command) string { + if cmd.FullName() == "coder" { + return docgenenv.FrontMatter(cliIndexRoute) + } + return docgenenv.FrontMatter(cliCommandRoute(cmd)) + }, + // generatedContentBanner emits the shared body banner that marks + // the whole page as generated, sourced from one constant so the CLI + // and API generators cannot drift on its wording. + "generatedContentBanner": func() string { + return docgenenv.GeneratedContentBanner + }, "tableHeader": func() string { return `| | | | --- | --- |` @@ -87,6 +102,28 @@ func fullName(cmd *serpent.Command) string { return strings.TrimPrefix(cmd.FullName(), "coder ") } +// cliCommandRoute maps a serpent command to the docgenenv.Route whose per-page +// metadata the CLI generator mirrors into that command's page front matter. +// main layers the manifest Path onto the same value when it rebuilds the nav +// tree, so the per-command field mapping lives in exactly one place. +func cliCommandRoute(cmd *serpent.Command) docgenenv.Route { + return docgenenv.Route{ + Title: fullName(cmd), + Description: cmd.Short, + } +} + +// cliIndexRouteFrom returns the CLI index page's route: a copy of the "Command +// Line" manifest route with its nav children dropped. Copying the whole route +// instead of enumerating fields means the index front matter mirrors every +// current and future per-page field (including curated icon_path and state) +// automatically, so it can't drift from the shared docgenenv.FrontMatter +// emitter the way a hand-written field list would. +func cliIndexRouteFrom(cmdLine docgenenv.Route) docgenenv.Route { + cmdLine.Children = nil + return cmdLine +} + func fmtDocFilename(cmd *serpent.Command) string { if cmd.FullName() == "coder" { // Special case for index. diff --git a/scripts/clidocgen/main.go b/scripts/clidocgen/main.go index 9550308cef..2fb698082e 100644 --- a/scripts/clidocgen/main.go +++ b/scripts/clidocgen/main.go @@ -1,10 +1,11 @@ package main import ( + "cmp" "encoding/json" "os" "path/filepath" - "sort" + "slices" "github.com/coder/coder/v2/enterprise/cli" "github.com/coder/coder/v2/scripts/atomicwrite" @@ -13,21 +14,11 @@ import ( "github.com/coder/serpent" ) -// route is an individual page object in the docs manifest.json. -type route struct { - Title string `json:"title,omitempty"` - Description string `json:"description,omitempty"` - Path string `json:"path,omitempty"` - IconPath string `json:"icon_path,omitempty"` - State []string `json:"state,omitempty"` - Children []route `json:"children,omitempty"` -} - -// manifest describes the entire documentation index. -type manifest struct { - Versions []string `json:"versions,omitempty"` - Routes []route `json:"routes,omitempty"` -} +// cliIndexRoute holds the "Command Line" manifest route's metadata so the +// generated index page can mirror it through the shared docgenenv.FrontMatter +// emitter (see the frontMatter template func in gen.go). main populates it +// before genTree runs. +var cliIndexRoute docgenenv.Route func deleteEmptyDirs(dir string) error { return filepath.Walk(dir, func(path string, info os.FileInfo, err error) error { @@ -74,6 +65,23 @@ func main() { cliMarkdownDir = filepath.Join(docsDir, "reference/cli") } + // Load the manifest up front so the generated index page can mirror the + // "Command Line" route's curated metadata (title/description/icon_path) + // instead of the root command name. + manifestPath := filepath.Join(docsDir, "manifest.json") + man, err := docgenenv.LoadManifest(manifestPath) + if err != nil { + flog.Fatalf("%v", err) + } + cmdLine := man.FindRoute("Reference", "Command Line") + if cmdLine == nil { + flog.Fatalf("could not find Command Line route in manifest %q", manifestPath) + } + // Mirror the whole "Command Line" route (minus its nav children) so the + // index page front matter carries every current and future per-page field + // automatically, the same way the API index mirrors its manifest route. + cliIndexRoute = cliIndexRouteFrom(*cmdLine) + cmd, err := root.Command(root.EnterpriseSubcommands()) if err != nil { flog.Fatalf("creating command: %v", err) @@ -113,57 +121,25 @@ func main() { flog.Fatalf("deleting empty dirs: %v", err) } - // Update manifest - manifestPath := filepath.Join(docsDir, "manifest.json") - - manifestByt, err := os.ReadFile(manifestPath) - if err != nil { - flog.Fatalf("reading manifest: %v", err) - } - - var manifest manifest - err = json.Unmarshal(manifestByt, &manifest) - if err != nil { - flog.Fatalf("unmarshalling manifest: %v", err) - } - - var found bool - for i := range manifest.Routes { - rt := &manifest.Routes[i] - if rt.Title != "Reference" { - continue - } - for j := range rt.Children { - child := &rt.Children[j] - if child.Title != "Command Line" { - continue - } - child.Children = nil - found = true - for path, cmd := range wroteMap { - relPath, err := filepath.Rel(docsDir, path) - if err != nil { - flog.Fatalf("getting relative path: %v", err) - } - child.Children = append(child.Children, route{ - Title: fullName(cmd), - Description: cmd.Short, - Path: relPath, - }) - } - // Sort children by title because wroteMap iteration is - // non-deterministic. - sort.Slice(child.Children, func(i, j int) bool { - return child.Children[i].Title < child.Children[j].Title - }) + // Rebuild the "Command Line" route's children from the generated pages. + // cmdLine aliases the manifest loaded above, so mutating it updates the + // manifest in place. + cmdLine.Children = nil + for path, cmd := range wroteMap { + relPath, err := filepath.Rel(docsDir, path) + if err != nil { + flog.Fatalf("getting relative path: %v", err) } + child := cliCommandRoute(cmd) + child.Path = relPath + cmdLine.Children = append(cmdLine.Children, child) } + // Sort children by title because wroteMap iteration is non-deterministic. + slices.SortFunc(cmdLine.Children, func(a, b docgenenv.Route) int { + return cmp.Compare(a.Title, b.Title) + }) - if !found { - flog.Fatalf("could not find Command Line route in manifest") - } - - manifestByt, err = json.MarshalIndent(manifest, "", " ") + manifestByt, err := json.MarshalIndent(man, "", " ") if err != nil { flog.Fatalf("marshaling manifest: %v", err) } diff --git a/scripts/clidocgen/route_test.go b/scripts/clidocgen/route_test.go new file mode 100644 index 0000000000..3b8dad0901 --- /dev/null +++ b/scripts/clidocgen/route_test.go @@ -0,0 +1,54 @@ +package main + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/coder/coder/v2/scripts/docgenenv" + "github.com/coder/serpent" +) + +// TestCLICommandRoute pins the per-command metadata mapping the CLI generator +// mirrors into page front matter: title from the command's full name and +// description from its Short, with no curated fields invented. Path, IconPath, +// and State stay zero here (Path is layered on by the manifest rebuild; +// IconPath/State are index/manifest-authored only), so the shared emitter +// cannot silently gain a CLI-only value. +func TestCLICommandRoute(t *testing.T) { + t.Parallel() + + got := cliCommandRoute(&serpent.Command{Use: "ping", Short: "Ping a workspace"}) + require.Equal(t, "ping", got.Title) + require.Equal(t, "Ping a workspace", got.Description) + require.Empty(t, got.Path) + require.Empty(t, got.IconPath) + require.Nil(t, got.State) +} + +// TestCLIIndexRouteMirrorsManifest pins the CLI index page's route: it copies +// the whole "Command Line" manifest route (minus nav children) so curated, +// index-only fields (icon_path, state) still reach the shared front-matter +// emitter. No Command Line route carries icon_path or state today, so neither +// the golden regen nor the per-command test above exercises this arm. +func TestCLIIndexRouteMirrorsManifest(t *testing.T) { + t.Parallel() + + src := docgenenv.Route{ + Title: "Command Line", + Description: "Learn how to use Coder CLI", + IconPath: "./images/icons/terminal.svg", + State: []string{"beta"}, + Children: []docgenenv.Route{{Title: "ping", Path: "reference/cli/ping.md"}}, + } + got := cliIndexRouteFrom(src) + require.Equal(t, src.Title, got.Title) + require.Equal(t, src.Description, got.Description) + require.Equal(t, src.IconPath, got.IconPath) + require.Equal(t, src.State, got.State) + require.Nil(t, got.Children, "nav children must not leak into index front matter") + + fm := docgenenv.FrontMatter(got) + require.Contains(t, fm, `icon_path: "./images/icons/terminal.svg"`) + require.Contains(t, fm, "state:\n - beta") +} diff --git a/scripts/docgenenv/frontmatter.go b/scripts/docgenenv/frontmatter.go new file mode 100644 index 0000000000..1e363e82bf --- /dev/null +++ b/scripts/docgenenv/frontmatter.go @@ -0,0 +1,65 @@ +package docgenenv + +import "strings" + +// generatedMarker is the YAML comment placed as the first line inside every +// generated reference page's front matter. It follows the canonical +// "Code generated ... DO NOT EDIT." convention so the signal is recognizable at +// the top of the file. Because it lives inside the front matter fence, every +// coder.com surface (rendered HTML, the .md proxy twin, and the llms corpus) +// strips it with the rest of the block, so it never reaches readers. +const generatedMarker = "# Code generated by make gen. DO NOT EDIT." + +// GeneratedContentBanner is the HTML comment placed in the Markdown body of +// every generated reference page, directly below the front matter. The in-fence +// generatedMarker flags the page metadata as generated; this body banner flags +// the whole page as generated, so an editor who reads past the front matter is +// still warned. Both documentation generators reference this one constant so +// the wording cannot drift between them. +const GeneratedContentBanner = "" + +// FrontMatter renders r's metadata (title plus any description, icon_path, and +// state) as a YAML front matter block. The block opens with generatedMarker, +// carries the fences, and ends with the blank line that separates it from the +// Markdown body. Optional fields are omitted when empty. +// +// Both documentation generators emit their front matter through this single +// function so a new per-page metadata field is wired in one place instead of +// drifting between the CLI template and the API generator. Structural manifest +// fields (path, children) are intentionally not mirrored here. +func FrontMatter(r Route) string { + // strings.Builder and bytes.Buffer expose only error-returning Write + // methods, which the revive unhandled-error linter flags, so assemble the + // block as a []string and join it. + lines := []string{ + "---", + generatedMarker, + "title: " + YAMLScalar(r.Title), + } + if r.Description != "" { + lines = append(lines, "description: "+YAMLScalar(r.Description)) + } + if r.IconPath != "" { + lines = append(lines, "icon_path: "+YAMLScalar(r.IconPath)) + } + if len(r.State) > 0 { + lines = append(lines, "state:") + for _, s := range r.State { + lines = append(lines, " - "+YAMLScalar(s)) + } + } + // The trailing empty strings produce the closing fence followed by the + // blank line that must separate front matter from the body. + lines = append(lines, "---", "", "") + return strings.Join(lines, "\n") +} + +// GeneratedHeader returns the full generated-page preamble: the front matter +// block (from FrontMatter) followed by GeneratedContentBanner and the blank +// line before the Markdown body. The API generator prepends this to every page +// so CLI and API reference pages share the same two markers; the CLI template +// composes the equivalent preamble inline from the frontMatter and +// generatedContentBanner template helpers. +func GeneratedHeader(r Route) string { + return FrontMatter(r) + GeneratedContentBanner + "\n\n" +} diff --git a/scripts/docgenenv/frontmatter_test.go b/scripts/docgenenv/frontmatter_test.go new file mode 100644 index 0000000000..40fbaeaffe --- /dev/null +++ b/scripts/docgenenv/frontmatter_test.go @@ -0,0 +1,58 @@ +package docgenenv_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/coder/coder/v2/scripts/docgenenv" +) + +func TestFrontMatter(t *testing.T) { + t.Parallel() + + t.Run("TitleOnly", func(t *testing.T) { + t.Parallel() + + got := docgenenv.FrontMatter(docgenenv.Route{Title: "General"}) + require.Equal(t, "---\n# Code generated by make gen. DO NOT EDIT.\ntitle: General\n---\n\n", got) + }) + + // AllFields exercises every optional branch, including icon_path (the + // curated field the index pages rely on, previously uncovered) and the + // state sequence. + t.Run("AllFields", func(t *testing.T) { + t.Parallel() + + got := docgenenv.FrontMatter(docgenenv.Route{ + Title: "REST API", + Description: "Learn how to use Coderd API", + IconPath: "./images/icons/api.svg", + State: []string{"early access"}, + }) + want := "---\n" + + "# Code generated by make gen. DO NOT EDIT.\n" + + "title: REST API\n" + + "description: Learn how to use Coderd API\n" + + `icon_path: "./images/icons/api.svg"` + "\n" + + "state:\n" + + " - early access\n" + + "---\n\n" + require.Equal(t, want, got) + }) +} + +// TestGeneratedHeader pins the full generated-page preamble: the front matter +// block (with its in-fence marker) followed by the body banner and the blank +// line before the body. +func TestGeneratedHeader(t *testing.T) { + t.Parallel() + + got := docgenenv.GeneratedHeader(docgenenv.Route{Title: "General"}) + want := "---\n" + + "# Code generated by make gen. DO NOT EDIT.\n" + + "title: General\n" + + "---\n\n" + + "\n\n" + require.Equal(t, want, got) +} diff --git a/scripts/docgenenv/manifest.go b/scripts/docgenenv/manifest.go new file mode 100644 index 0000000000..32635f7de0 --- /dev/null +++ b/scripts/docgenenv/manifest.go @@ -0,0 +1,72 @@ +package docgenenv + +import ( + "encoding/json" + "os" + + "golang.org/x/xerrors" +) + +// Route is an individual page object in the docs manifest.json. Per-page +// metadata (title, description, icon_path, state) is mirrored into page front +// matter by the doc generators; the structural fields (path, children) stay in +// the manifest. +type Route struct { + Title string `json:"title,omitempty"` + Description string `json:"description,omitempty"` + Path string `json:"path,omitempty"` + IconPath string `json:"icon_path,omitempty"` + State []string `json:"state,omitempty"` + Children []Route `json:"children,omitempty"` +} + +// Manifest describes the entire documentation index (docs/manifest.json). +type Manifest struct { + Versions []string `json:"versions,omitempty"` + Routes []Route `json:"routes,omitempty"` +} + +// LoadManifest reads and unmarshals the manifest.json at path. Its errors wrap +// the path and cause, so callers should return the error as-is rather than +// wrapping it again. +func LoadManifest(path string) (*Manifest, error) { + b, err := os.ReadFile(path) + if err != nil { + return nil, xerrors.Errorf("read manifest %q: %w", path, err) + } + var m Manifest + if err := json.Unmarshal(b, &m); err != nil { + return nil, xerrors.Errorf("unmarshal manifest %q: %w", path, err) + } + return &m, nil +} + +// FindRoute walks the manifest, following titles as a breadcrumb from the +// top-level routes, and returns a pointer to the matching route (or nil if any +// title in the path has no match). The returned pointer aliases the manifest, +// so mutating it (for example, replacing Children) updates the manifest in place. +// +// Both documentation generators resolve their target route through this single +// traversal so the route they read metadata from and the route they rewrite +// cannot drift apart. +func (m *Manifest) FindRoute(titles ...string) *Route { + if m == nil || len(titles) == 0 { + return nil + } + routes := m.Routes + var match *Route + for _, title := range titles { + match = nil + for i := range routes { + if routes[i].Title == title { + match = &routes[i] + break + } + } + if match == nil { + return nil + } + routes = match.Children + } + return match +} diff --git a/scripts/docgenenv/manifest_test.go b/scripts/docgenenv/manifest_test.go new file mode 100644 index 0000000000..983791bb93 --- /dev/null +++ b/scripts/docgenenv/manifest_test.go @@ -0,0 +1,39 @@ +package docgenenv_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + + "github.com/coder/coder/v2/scripts/docgenenv" +) + +func TestManifestFindRoute(t *testing.T) { + t.Parallel() + + m := &docgenenv.Manifest{ + Routes: []docgenenv.Route{ + {Title: "Reference", Children: []docgenenv.Route{ + {Title: "Command Line", Description: "Learn how to use Coder CLI"}, + {Title: "REST API", Description: "Learn how to use Coderd API", Children: []docgenenv.Route{ + {Title: "General"}, + }}, + }}, + }, + } + + rest := m.FindRoute("Reference", "REST API") + require.NotNil(t, rest) + require.Equal(t, "Learn how to use Coderd API", rest.Description) + + // The returned pointer aliases the manifest, so mutations persist. + rest.Children = nil + require.Nil(t, m.FindRoute("Reference", "REST API").Children) + + require.NotNil(t, m.FindRoute("Reference", "Command Line")) + + // Misses return nil rather than panicking. + require.Nil(t, m.FindRoute("Reference", "Nope")) + require.Nil(t, m.FindRoute()) + require.Nil(t, m.FindRoute("REST API")) // Not a top-level route. +} diff --git a/scripts/docgenenv/yaml.go b/scripts/docgenenv/yaml.go new file mode 100644 index 0000000000..7c46673c58 --- /dev/null +++ b/scripts/docgenenv/yaml.go @@ -0,0 +1,52 @@ +package docgenenv + +import ( + "encoding/json" + "regexp" + "strings" +) + +// safeScalarRegex matches values that can be emitted as a bare (unquoted) YAML +// scalar: they start with an alphanumeric and contain only alphanumerics, +// spaces, and a small set of punctuation YAML never treats specially. A +// trailing space is disallowed because YAML strips it on read, so a bare scalar +// ending in a space would not round-trip back to the original string. +var safeScalarRegex = regexp.MustCompile(`^[A-Za-z0-9]([A-Za-z0-9 ._/-]*[A-Za-z0-9._/-])?$`) + +// numberScalarRegex matches values YAML would resolve to an integer or float. +var numberScalarRegex = regexp.MustCompile(`^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$`) + +// YAMLScalar renders s as a YAML scalar suitable for a front matter value. +// Simple values are emitted verbatim. Anything YAML could misparse, such as +// special characters or a bare word/number YAML would otherwise resolve to a +// bool, null, or number, is JSON-encoded, which is valid YAML that quotes and +// escapes the value so it round-trips back to the original string. +// +// Both the CLI and API documentation generators share this helper so their +// front-matter escaping cannot silently diverge. +func YAMLScalar(s string) string { + if isBareScalar(s) { + return s + } + b, err := json.Marshal(s) + if err != nil { + return `""` + } + return string(b) +} + +// isBareScalar reports whether s can be emitted unquoted without YAML +// reinterpreting it as a non-string type. +func isBareScalar(s string) bool { + if !safeScalarRegex.MatchString(s) { + return false + } + // Even when every character is safe, quote values YAML would resolve to a + // bool or null (e.g. a title of "true" or "null") so they stay strings. + switch strings.ToLower(s) { + case "true", "false", "yes", "no", "on", "off", "y", "n", "null", "none", "~": + return false + } + // Likewise quote anything that parses as a number (e.g. "123", "1.5"). + return !numberScalarRegex.MatchString(s) +} diff --git a/scripts/docgenenv/yaml_test.go b/scripts/docgenenv/yaml_test.go new file mode 100644 index 0000000000..7e2c0444b5 --- /dev/null +++ b/scripts/docgenenv/yaml_test.go @@ -0,0 +1,99 @@ +package docgenenv_test + +import ( + "testing" + + "github.com/stretchr/testify/require" + "gopkg.in/yaml.v3" + + "github.com/coder/coder/v2/scripts/docgenenv" +) + +// TestYAMLScalarRoundTrip asserts the emitted scalar parses back to the exact +// input string. Unmarshaling into a Go string returns the scalar's text +// regardless of the type YAML would resolve it to, so this catches the values +// that break parsing or resolve away (quotes, colons, newlines, trailing space, +// null and ~) but not the reserved-word or number quoting intent. That intent +// is pinned directly in TestYAMLScalarBareWhenSafe. +func TestYAMLScalarRoundTrip(t *testing.T) { + t.Parallel() + + cases := []string{ + // Values seen in practice today. + "server", + "templates create", + "Start a Coder server", + "early access", + "DEPRECATED: Create a template from the current directory or as specified by flag", + "./images/icons/api.svg", + // Special characters that must be escaped. + `has "quotes" and: a colon`, + "trailing backtick `code`", + "line one\nline two", + // Trailing space: YAML strips it on read, so a bare scalar would not + // round-trip. + "trailing space ", + // Values YAML would otherwise resolve to a non-string type. + "true", + "False", + "NULL", + "no", + "on", + "123", + "1.5", + "-42", + "~", + } + for _, in := range cases { + t.Run(in, func(t *testing.T) { + t.Parallel() + + doc := "value: " + docgenenv.YAMLScalar(in) + "\n" + var got struct { + Value string `yaml:"value"` + } + require.NoErrorf(t, yaml.Unmarshal([]byte(doc), &got), "emitted YAML must parse: %q", doc) + require.Equalf(t, in, got.Value, "scalar must round-trip as a string, doc=%q", doc) + }) + } +} + +// TestYAMLScalarBareWhenSafe pins the bare-vs-quoted decision directly against +// the emitted text, which the round-trip test cannot do for the reserved-word +// and number class (unmarshaling into a Go string hands back the text whether +// or not YAMLScalar quoted it). Common values stay bare so regenerated pages +// don't churn; anything a YAML reader would resolve to a bool, null, or number +// is quoted. Trimming the isBareScalar switch or the number check fails here. +func TestYAMLScalarBareWhenSafe(t *testing.T) { + t.Parallel() + + // Safe, stringy values stay bare. + for _, in := range []string{ + "server", + "templates create", + "Start a Coder server", + "early access", + } { + require.Equalf(t, in, docgenenv.YAMLScalar(in), "safe value %q must stay bare", in) + } + + // Values that look bare but a YAML reader would resolve to a non-string + // type must be quoted. json.Marshal wraps each of these verbatim, so the + // expected form is simply the input in double quotes. + for _, in := range []string{ + // YAML 1.1 bool aliases, in the casings isBareScalar folds. + "true", "false", "yes", "no", "on", "off", "y", "n", "none", + "True", "False", "Yes", "No", "On", "Off", "None", "NULL", + // Null forms. + "null", "~", + // Numbers (integer, float, signed, scientific). + "123", "1.5", "-42", "+7", "1e3", + } { + require.Equalf(t, `"`+in+`"`, docgenenv.YAMLScalar(in), "ambiguous value %q must be quoted", in) + } + + // Values with characters YAML would misparse are quoted too. + require.Equal(t, `"./images/icons/api.svg"`, docgenenv.YAMLScalar("./images/icons/api.svg")) + // A trailing space forces quoting so the value round-trips. + require.Equal(t, `"foo "`, docgenenv.YAMLScalar("foo ")) +}