From 2e64d3c267a6c68d8b4a53233265773cc4930716 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Sun, 15 Mar 2026 10:39:32 -0700 Subject: [PATCH 1/2] few more bits of docs improvement --- CONTRIBUTING.md | 12 +++++++++--- docs/get-started/quickstart.md | 14 ++------------ docs/index.md | 4 +--- 3 files changed, 12 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9211b440..70bf5ef4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,6 +42,7 @@ Skills live in `.agents/skills/`. Your agent's harness can discover and load the | Triage | `triage-issue` | Assess, classify, and route community-filed issues | | Platform | `generate-sandbox-policy` | Generate YAML sandbox policies from requirements or API docs | | Platform | `tui-development` | Development guide for the ratatui-based terminal UI | +| Documentation | `update-docs-from-commits` | Scan recent commits and draft doc updates for user-facing changes | | Maintenance | `sync-agent-infra` | Detect and fix drift across agent-first infrastructure files | | Reference | `sbom` | Generate SBOMs and resolve dependency licenses | @@ -153,14 +154,19 @@ These are the primary `mise` tasks for day-to-day development: ## Documentation If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under `docs/` in the same PR. -See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the doc structure, style guide, and formatting rules. -Build and preview docs locally: +To ensure your doc changes follow NVIDIA documentation style, use the `update-docs-from-commits` skill. +It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in `docs/CONTRIBUTING.md`. + +To build and preview docs locally: ```bash -mise run docs +mise run docs # to build the docs locally +mise run docs:serve # to serve locally and automatically rebuild on changes ``` +See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for more details. + ## Pull Requests 1. Create a feature branch from `main`. diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md index d6f2c84a..4181b5d1 100644 --- a/docs/get-started/quickstart.md +++ b/docs/get-started/quickstart.md @@ -55,17 +55,7 @@ $ uv pip install openshell ``` :::{tip} -To find the CLI reference, run: -- `openshell --help` to see all available commands. -- `openshell --help` for detailed usage of any subcommand. - -For example: - -```console -$ openshell --help -$ openshell gateway --help -$ openshell sandbox create --help -``` +Run `openshell --help` in your terminal to see the full CLI reference, including all commands and flags. You can also clone the [NVIDIA OpenShell GitHub repository](https://github.com/NVIDIA/OpenShell) and use the `/openshell-cli` skill to load the CLI reference into your agent. ::: ## Deploy a Gateway (Optional) @@ -78,7 +68,7 @@ To start the gateway explicitly or deploy to a remote host, choose the tab that ::::{tab-item} Brev :::{note} -Deploy an OpenShell gateway on Brev by clicking **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3AaK9NmCzWp3pVyUDNNFBt805FT). +Deploy an OpenShell gateway on Brev by clicking **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg). ::: After the instance starts running, find the gateway URL in the Brev console under **Using Secure Links**. diff --git a/docs/index.md b/docs/index.md index aa4cbf56..fdccda78 100644 --- a/docs/index.md +++ b/docs/index.md @@ -105,12 +105,10 @@ Install the CLI and create your first sandbox in two commands. ``` -Run `openshell --help` in your terminal to see the full CLI reference, including all commands and flags. -Run `openshell --help` for detailed usage of any subcommand. +Run `openshell --help` in your terminal to see the full CLI reference, including all commands and flags. You can also clone the [OpenShell repository](https://github.com/NVIDIA/OpenShell) and use the `/openshell-cli` skill to load the CLI reference into your agent. Proceed to the [Quickstart](get-started/quickstart.md) for more details. - --- ## Explore From 93fa5b921df258797345456ee24b6d2d764ddc39 Mon Sep 17 00:00:00 2001 From: Miyoung Choi Date: Sun, 15 Mar 2026 10:42:53 -0700 Subject: [PATCH 2/2] update docs update skill --- .agents/skills/update-docs-from-commits/SKILL.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.agents/skills/update-docs-from-commits/SKILL.md b/.agents/skills/update-docs-from-commits/SKILL.md index 08cb234d..5b68a298 100644 --- a/.agents/skills/update-docs-from-commits/SKILL.md +++ b/.agents/skills/update-docs-from-commits/SKILL.md @@ -21,7 +21,7 @@ Scan recent git history for commits that affect user-facing behavior and draft d ## Step 1: Identify Relevant Commits -Determine the commit range. The user may provide one explicitly (e.g., "since v0.2.0" or "last 30 commits"). If not, default to commits since the last release tag or the last 50 commits, whichever is smaller. +Determine the commit range. The user may provide one explicitly (e.g., "since v0.2.0" or "last 30 commits"). If not, default to commits since the head of the main branch. ```bash # Commits since a tag @@ -95,7 +95,6 @@ Write the doc update following the rules in `docs/CONTRIBUTING.md`. Key reminder - **No em dashes** unless used sparingly. Prefer commas or separate sentences. - **Start sections with an introductory sentence** that orients the reader. - **No superlatives.** Say what the feature does, not how great it is. -- **One sentence per line** in the source (for clean diffs). - **Code examples use `console` language** with `$` prompt prefix. - **Include the SPDX header** if creating a new page. - **Match existing frontmatter format** if creating a new page.