Skip to content

Commit 8b8fd09

Browse files
steipetesteipete
committed
docs: add generated command pages site
1 parent 33284f0 commit 8b8fd09

449 files changed

Lines changed: 21975 additions & 468 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/pages.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "scripts/gen-command-reference.sh"
10+
- "scripts/build-docs-site.mjs"
11+
- "Makefile"
12+
- ".github/workflows/pages.yml"
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
24+
jobs:
25+
deploy:
26+
name: Deploy docs
27+
runs-on: ubuntu-latest
28+
timeout-minutes: 10
29+
environment:
30+
name: github-pages
31+
url: ${{ steps.deployment.outputs.page_url }}
32+
steps:
33+
- name: Check out
34+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
35+
36+
- name: Set up Go
37+
uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
38+
with:
39+
go-version-file: go.mod
40+
cache: true
41+
42+
- name: Set up Node
43+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
44+
with:
45+
node-version: "24"
46+
47+
- name: Build docs site
48+
run: make docs-site
49+
50+
- name: Configure Pages
51+
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
55+
with:
56+
path: dist/docs-site
57+
58+
- name: Deploy
59+
id: deployment
60+
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,4 @@ internal/cmd/safety_profile_baked_gen.go
4141

4242
# Node (optional dev scripts)
4343
node_modules/
44+
dist/

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ SHELL := /bin/bash
33
# `make` should build the binary by default.
44
.DEFAULT_GOAL := build
55

6-
.PHONY: build build-safe gog gogcli gog-help gogcli-help help fmt fmt-check lint test ci tools docs-commands
6+
.PHONY: build build-safe gog gogcli gog-help gogcli-help help fmt fmt-check lint test ci tools docs-commands docs-site docs-check
77
.PHONY: worker-ci
88

99
BIN_DIR := $(CURDIR)/bin
@@ -70,6 +70,11 @@ help: gog-help
7070
docs-commands: build
7171
@scripts/gen-command-reference.sh docs/commands.generated.md
7272

73+
docs-site: docs-commands
74+
@node scripts/build-docs-site.mjs
75+
76+
docs-check: docs-site
77+
7378
tools:
7479
@mkdir -p $(TOOLS_DIR)
7580
@if [ -x "$(GOFUMPT)" ] && [ -x "$(GOIMPORTS)" ] && [ -x "$(GOLANGCI_LINT)" ] && [ "$$(cat $(TOOLS_STAMP) 2>/dev/null)" = "$(TOOLS_VERSION)" ]; then \

‎README.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1960,12 +1960,25 @@ Pinned tools (installed into `.tools/`):
19601960

19611961
CI runs format checks, tests, and lint on push/PR.
19621962

1963-
Regenerate the expanded command reference from the live schema when CLI surface changes:
1963+
Documentation is split between hand-written topic pages in `docs/` and generated
1964+
per-command pages in `docs/commands/`. Every CLI command should have a docs page;
1965+
do not hand-edit generated command pages. Regenerate them from the live schema
1966+
whenever command names, flags, aliases, arguments, or help text change:
19641967

19651968
```bash
19661969
make docs-commands
19671970
```
19681971

1972+
Build the GitHub Pages site locally:
1973+
1974+
```bash
1975+
make docs-site
1976+
open dist/docs-site/index.html
1977+
```
1978+
1979+
The Pages workflow rebuilds the command pages and publishes the static site from
1980+
`dist/docs-site` using the custom domain in `docs/CNAME`.
1981+
19691982
### Integration Tests (Live Google APIs)
19701983

19711984
Opt-in tests that hit real Google APIs using your stored `gog` credentials/tokens.

‎docs/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# gog Docs
2+
3+
`gog` is a single CLI for Google Workspace automation: Gmail, Calendar, Drive,
4+
Docs, Sheets, Slides, Contacts, Tasks, People, Forms, Apps Script, Groups, Admin,
5+
Keep, and related agent workflows.
6+
7+
## Start Here
8+
9+
- Install and authenticate from the repository
10+
[README](https://github.com/steipete/gogcli#readme).
11+
- Read [Auth Clients](auth-clients.md) when setting up OAuth clients, service
12+
accounts, or Workspace domain-wide delegation.
13+
- Read [Command Guards and Baked Safety Profiles](safety-profiles.md) when
14+
running `gog` from agents or automation.
15+
- Open the [Command Index](commands/README.md) for generated docs for every CLI
16+
command.
17+
18+
## Common Paths
19+
20+
```bash
21+
gog auth add you@gmail.com --services gmail,calendar,drive
22+
gog gmail search 'newer_than:7d' --max 10
23+
gog gmail get <messageId> --sanitize-content --json
24+
gog calendar events --today
25+
gog drive ls --max 20
26+
```
27+
28+
## Command Docs
29+
30+
Every command page under `docs/commands/` is generated from
31+
`gog schema --json`. Do not hand-edit generated command pages. After changing
32+
commands, flags, aliases, arguments, or help text, run:
33+
34+
```bash
35+
make docs-commands
36+
```
37+
38+
Then build the GitHub Pages site locally:
39+
40+
```bash
41+
make docs-site
42+
open dist/docs-site/index.html
43+
```
44+
45+
The site is intentionally static: no framework, no package install, and no
46+
client-side dependency beyond a small navigation script embedded by the builder.

0 commit comments

Comments
 (0)