Skip to content

Commit 2bf9969

Browse files
miyoungcmiyoungc
authored
chore: add docs contributing guides and skills (#301)
* add docs contributing guides and skills * add section
1 parent 17f3a64 commit 2bf9969

5 files changed

Lines changed: 352 additions & 0 deletions

File tree

‎.agents/skills/update-docs-from-commits/SKILL.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
name: update-docs-from-commits
3+
description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.
4+
---
5+
6+
# Update Docs from Commits
7+
8+
Scan recent git history for commits that affect user-facing behavior and draft documentation updates for each.
9+
10+
## Prerequisites
11+
12+
- You must be in the OpenShell git repository.
13+
- The `docs/` directory must exist with the current doc set.
14+
- Read `docs/CONTRIBUTING.md` before writing any content. It contains the style guide and formatting rules.
15+
16+
## When to Use
17+
18+
- After a batch of features or fixes has landed and docs may be stale.
19+
- Before a release, to catch any doc gaps.
20+
- When a contributor asks "what docs need updating?"
21+
22+
## Step 1: Identify Relevant Commits
23+
24+
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.
25+
26+
```bash
27+
# Commits since a tag
28+
git log v0.2.0..HEAD --oneline --no-merges
29+
30+
# Or last 50 commits
31+
git log -50 --oneline --no-merges
32+
```
33+
34+
Filter to commits that are likely to affect docs. Look for these signals:
35+
36+
1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes. `chore`, `ci`, `test` commits rarely need doc updates.
37+
2. **Files changed**: Changes to `crates/openshell-cli/`, `python/`, `proto/`, `deploy/`, or policy-related code are high-signal.
38+
3. **Ignore**: Changes limited to `tests/`, `e2e/`, `.github/`, `tasks/`, or internal-only modules.
39+
40+
```bash
41+
# Show files changed per commit to assess impact
42+
git log v0.2.0..HEAD --oneline --no-merges --name-only
43+
```
44+
45+
## Step 2: Map Commits to Doc Pages
46+
47+
For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point:
48+
49+
| Code area | Likely doc page(s) |
50+
|---|---|
51+
| `crates/openshell-cli/` (gateway commands) | `docs/sandboxes/manage-gateways.md` |
52+
| `crates/openshell-cli/` (sandbox commands) | `docs/sandboxes/manage-sandboxes.md` |
53+
| `crates/openshell-cli/` (provider commands) | `docs/sandboxes/manage-providers.md` |
54+
| `crates/openshell-cli/` (new top-level command) | May need a new page or `docs/reference/` entry |
55+
| `crates/openshell-proxy/` or policy code | `docs/sandboxes/policies.md`, `docs/reference/policy-schema.md` |
56+
| `crates/openshell-inference/` | `docs/inference/configure.md` |
57+
| `python/` (SDK changes) | `docs/reference/` or `docs/get-started/quickstart.md` |
58+
| `proto/` (API changes) | `docs/reference/` |
59+
| `deploy/` (Dockerfile, Helm) | `docs/sandboxes/manage-gateways.md`, `docs/about/architecture.md` |
60+
| Community sandbox definitions | `docs/sandboxes/community-sandboxes.md` |
61+
62+
If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
63+
64+
## Step 3: Read the Commit Details
65+
66+
For each commit that needs a doc update, read the full diff to understand the change:
67+
68+
```bash
69+
git show <commit-hash> --stat
70+
git show <commit-hash>
71+
```
72+
73+
Extract:
74+
75+
- What changed (new flag, renamed command, changed default, new feature).
76+
- Why it changed (from the commit message body, linked issue, or PR description).
77+
- Any breaking changes or migration steps.
78+
79+
## Step 4: Read the Current Doc Page
80+
81+
Before editing, read the full target doc page to understand its current content and structure:
82+
83+
```bash
84+
# Read the file
85+
```
86+
87+
Identify where the new content should go. Follow the page's existing structure.
88+
89+
## Step 5: Draft the Update
90+
91+
Write the doc update following the rules in `docs/CONTRIBUTING.md`. Key reminders:
92+
93+
- **Active voice, present tense, second person.**
94+
- **No unnecessary bold.** Reserve bold for UI labels and parameter names.
95+
- **No em dashes** unless used sparingly. Prefer commas or separate sentences.
96+
- **Start sections with an introductory sentence** that orients the reader.
97+
- **No superlatives.** Say what the feature does, not how great it is.
98+
- **One sentence per line** in the source (for clean diffs).
99+
- **Code examples use `console` language** with `$` prompt prefix.
100+
- **Include the SPDX header** if creating a new page.
101+
- **Match existing frontmatter format** if creating a new page.
102+
- **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia.
103+
- **Always capitalize OpenShell correctly.** Wrong: openshell, Openshell, openShell.
104+
- **Do not number section titles.** Wrong: "Section 1: Deploy a Gateway" or "Step 3: Verify." Use plain descriptive titles.
105+
- **No colons in titles.** Wrong: "Gateways: Deploy and Manage." Write "Deploy and Manage Gateways" instead.
106+
- **Use colons only to introduce a list.** Do not use colons as general-purpose punctuation between clauses.
107+
108+
When updating an existing page:
109+
110+
- Add content in the logical place within the existing structure.
111+
- Do not reorganize sections unless the change requires it.
112+
- Update any cross-references or "Next Steps" links if relevant.
113+
114+
When creating a new page:
115+
116+
- Follow the frontmatter template from `docs/CONTRIBUTING.md`.
117+
- Add the page to the appropriate `toctree` in `docs/index.md`.
118+
119+
## Step 6: Present the Results
120+
121+
After drafting all updates, present a summary to the user:
122+
123+
```
124+
## Doc Updates from Commits
125+
126+
### Updated pages
127+
- `docs/sandboxes/manage-gateways.md`: Added `--gpu` flag documentation (from commit abc1234).
128+
- `docs/reference/policy-schema.md`: Updated network policy schema for new `tls_inspect` field (from commit def5678).
129+
130+
### New pages needed
131+
- None (or list any new pages created).
132+
133+
### Commits with no doc impact
134+
- `chore(deps): bump tokio` (abc1234) — internal dependency, no user-facing change.
135+
- `test(e2e): add gateway timeout test` (def5678) — test-only change.
136+
```
137+
138+
## Step 7: Build and Verify
139+
140+
After making changes, build the docs locally:
141+
142+
```bash
143+
mise run docs
144+
```
145+
146+
Check for:
147+
148+
- Build warnings or errors.
149+
- Broken cross-references.
150+
- Correct rendering of new content.
151+
152+
## Tips
153+
154+
- When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior.
155+
- Group related commits that touch the same doc page into a single update rather than making multiple small edits.
156+
- If a commit is a breaking change, add a note at the top of the relevant section using a `:::{warning}` admonition.
157+
- PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories.
158+
159+
## Example Usage
160+
161+
User says: "Catch up the docs for everything merged since v0.2.0."
162+
163+
1. Run `git log v0.2.0..HEAD --oneline --no-merges --name-only`.
164+
2. Filter to `feat`, `fix`, `refactor`, `perf` commits touching user-facing code.
165+
3. Map each to a doc page.
166+
4. Read the commit diffs and current doc pages.
167+
5. Draft updates following the style guide.
168+
6. Present the summary.
169+
7. Build with `mise run docs` to verify.

‎AGENTS.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,9 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
9696
## Documentation
9797

9898
- When making changes, update the relevant documentation in the `architecture/` directory.
99+
- When changes affect user-facing behavior, also update the relevant pages under `docs/`.
100+
- Follow the style guide in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md): active voice, no unnecessary bold, no em dash overuse, no filler introductions.
101+
- Use the `update-docs-from-commits` skill to scan recent commits and draft doc updates.
99102

100103
## Security
101104

‎CONTRIBUTING.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,8 +147,20 @@ These are the primary `mise` tasks for day-to-day development:
147147
| `tasks/` | `mise` task definitions and build scripts |
148148
| `deploy/` | Dockerfiles, Helm chart, Kubernetes manifests |
149149
| `architecture/` | Architecture docs and plans |
150+
| `docs/` | User-facing documentation (Sphinx/MyST) |
150151
| `.agents/` | Agent skills and persona definitions |
151152

153+
## Documentation
154+
155+
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.
156+
See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the doc structure, style guide, and formatting rules.
157+
158+
Build and preview docs locally:
159+
160+
```bash
161+
mise run docs
162+
```
163+
152164
## Pull Requests
153165

154166
1. Create a feature branch from `main`.

‎docs/CONTRIBUTING.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Contributing to NVIDIA OpenShell Documentation
2+
3+
This guide covers how to write, edit, and review documentation for NVIDIA OpenShell. If you change code that affects user-facing behavior, update the relevant docs in the same PR.
4+
5+
## Use the Agent Skills
6+
7+
If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes skills that automate doc work. Use them before writing from scratch.
8+
9+
| Skill | What it does | When to use |
10+
|---|---|---|
11+
| `update-docs-from-commits` | Scans recent commits for user-facing changes and drafts doc updates. | After landing features, before a release, or to find doc gaps. |
12+
| `build-from-issue` | Plans and implements work from a GitHub issue, including doc updates. | When working from an issue that has doc impact. |
13+
14+
The skills live in `.agents/skills/` and follow the style guide below automatically. To use one, ask your agent to run it (e.g., "catch up the docs for everything merged since v0.2.0").
15+
16+
## When to Update Docs
17+
18+
Update documentation when your change:
19+
20+
- Adds, removes, or renames a CLI command or flag.
21+
- Changes default behavior or configuration.
22+
- Adds a new feature that users interact with.
23+
- Fixes a bug that the docs describe incorrectly.
24+
- Changes an API, protocol, or policy schema.
25+
26+
## Building Docs Locally
27+
28+
Verify the docs are built correctly by building them and checking the output.
29+
30+
To build the docs, run:
31+
32+
```bash
33+
mise run docs
34+
```
35+
36+
To serve the docs locally and automatically rebuild on changes, run:
37+
38+
```bash
39+
mise run docs:serve
40+
```
41+
42+
## Writing Conventions
43+
44+
### Format
45+
46+
- Docs use [MyST Markdown](https://myst-parser.readthedocs.io/), a Sphinx-compatible superset of CommonMark.
47+
- Every page starts with YAML frontmatter (title, description, topics, tags, content type).
48+
- Include the SPDX license header after frontmatter:
49+
```
50+
<!--
51+
SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
52+
SPDX-License-Identifier: Apache-2.0
53+
-->
54+
```
55+
56+
### Frontmatter Template
57+
58+
```yaml
59+
---
60+
title:
61+
page: Page Title
62+
nav: Short Nav Title
63+
description: One-sentence summary of the page.
64+
topics:
65+
- Generative AI
66+
- Cybersecurity
67+
tags:
68+
- Relevant
69+
- Tags
70+
content:
71+
type: concept | how_to | get_started | tutorial | reference
72+
difficulty: technical_beginner | technical_intermediate | technical_advanced
73+
audience:
74+
- engineer
75+
- data_scientist
76+
---
77+
```
78+
79+
### Page Structure
80+
81+
1. H1 heading matching the `title.page` value.
82+
2. A one- or two-sentence introduction stating what the page covers.
83+
3. Sections organized by task or concept, using H2 and H3. Start each section with an introductory sentence that orients the reader.
84+
4. A "Next Steps" section at the bottom linking to related pages.
85+
86+
## Style Guide
87+
88+
Write like you are explaining something to a colleague. Be direct, specific, and concise.
89+
90+
### Voice and Tone
91+
92+
- Use active voice. "The CLI creates a gateway" not "A gateway is created by the CLI."
93+
- Use second person ("you") when addressing the reader.
94+
- Use present tense. "The command returns an error" not "The command will return an error."
95+
- State facts. Do not hedge with "simply," "just," "easily," or "of course."
96+
97+
### Things to Avoid
98+
99+
These patterns are common in LLM-generated text and erode trust with technical readers. Remove them during review.
100+
101+
| Pattern | Problem | Fix |
102+
|---|---|---|
103+
| Unnecessary bold | "This is a **critical** step" on routine instructions. | Reserve bold for UI labels, parameter names, and genuine warnings. |
104+
| Em dashes everywhere | "The gateway — which runs in Docker — creates sandboxes." | Use commas or split into two sentences. Em dashes are fine sparingly but should not appear multiple times per paragraph. |
105+
| Superlatives | "OpenShell provides a powerful, robust, seamless experience." | Say what it does, not how great it is. |
106+
| Hedge words | "Simply run the command" or "You can easily configure..." | Drop the adverb. "Run the command." |
107+
| Emoji in prose | "🚀 Let's get started!" | No emoji in documentation prose. |
108+
| Rhetorical questions | "Want to secure your agents? Look no further!" | State the purpose directly. |
109+
110+
### Formatting Rules
111+
112+
- End every sentence with a period.
113+
- One sentence per line in the source file (makes diffs readable).
114+
- Use `code` formatting for CLI commands, file paths, flags, parameter names, and values.
115+
- Use code blocks with the `console` language for CLI examples. Prefix commands with `$`:
116+
```console
117+
$ openshell gateway start
118+
```
119+
- Use tables for structured comparisons. Keep tables simple (no nested formatting).
120+
- Use MyST admonitions (`:::{tip}`, `:::{note}`, `:::{warning}`) for callouts, not bold text.
121+
- Avoid nested admonitions.
122+
- Do not number section titles. Write "Deploy a Gateway" not "Section 1: Deploy a Gateway" or "Step 3: Verify."
123+
- Do not use colons in titles. Write "Deploy and Manage Gateways" not "Gateways: Deploy and Manage."
124+
- Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses.
125+
126+
### Word List
127+
128+
Use these consistently:
129+
130+
| Use | Do not use |
131+
|---|---|
132+
| gateway | Gateway (unless starting a sentence) |
133+
| sandbox | Sandbox (unless starting a sentence) |
134+
| CLI | cli, Cli |
135+
| API key | api key, API Key |
136+
| NVIDIA | Nvidia, nvidia |
137+
| OpenShell | Open Shell, openShell, Openshell, openshell |
138+
| mTLS | MTLS, mtls |
139+
| YAML | yaml, Yaml |
140+
141+
## Submitting Doc Changes
142+
143+
1. Create a branch following the project convention: `docs/<issue-id>-<description>/<username>`.
144+
2. Make your changes.
145+
3. Build locally with `mise run docs` and verify the output.
146+
4. Run `mise run pre-commit` to catch formatting issues.
147+
5. Open a PR with `docs:` as the conventional commit type.
148+
149+
```
150+
docs: update gateway deployment instructions
151+
```
152+
153+
If your doc change accompanies a code change, include both in the same PR and use the code change's commit type:
154+
155+
```
156+
feat(cli): add --gpu flag to gateway start
157+
```
158+
159+
## Reviewing Doc PRs
160+
161+
When reviewing documentation:
162+
163+
- Check that the style guide rules above are followed.
164+
- Watch for LLM-generated patterns (excessive bold, em dashes, filler).
165+
- Verify code examples are accurate and runnable.
166+
- Confirm cross-references and links are not broken.
167+
- Build locally to check rendering.

‎docs/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
exclude_patterns = [
4444
"README.md",
4545
"SETUP.md",
46+
"CONTRIBUTING.md",
4647
"_build/**",
4748
"_ext/**",
4849
]

0 commit comments

Comments
 (0)