docs: fix issues with layout and content found during review#53
docs: fix issues with layout and content found during review#53
Conversation
WalkthroughThis PR updates Suga documentation across the docs site. Changes include: new Suggested labels
Suggested reviewers
Pre-merge checks (1 passed, 1 warning, 1 inconclusive)❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
jyecusch
force-pushed
the
docs-updates
branch
2 times, most recently
from
f319704 to
514513c
Compare
jyecusch
force-pushed
the
docs-updates
branch
from
e458d11 to
eae82aa
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (36)
docs/guides/terraform-backend-config.mdx (5)
42-47: Step icon removal: looks good; consider removing code-block icon for consistencyIf the intent is a cleaner, icon-less Steps layout, drop the code-block icon here too.
Apply:
-```bash title="Generate Terraform Stack" icon="hammer" +```bash title="Generate Terraform Stack"
51-53: Also remove code-block icon for consistency (optional)Keeps presentation uniform with icon-less Steps.
-```bash title="Create Backend File" icon="file-plus" +```bash title="Create Backend File"
119-128: Step icon removal: also strip terminal/rocket icons in code blocks (optional)Prevents mixed icon usage inside an icon-less Steps block.
-```bash title="Initialize Terraform" icon="terminal" +```bash title="Initialize Terraform" @@ -```bash title="Deploy Infrastructure" icon="rocket" +```bash title="Deploy Infrastructure"
131-133: Nit: capitalize CDKTFMinor terminology polish.
- Only the cdktf files are managed by Suga. You can safely add custom `.tf` files to the stack directory to extend the configuration. + Only the CDKTF-generated files are managed by Suga. You can safely add custom `.tf` files to the stack directory to extend the configuration.
139-146: Clarify workspace commands (optional)terraform workspace new already switches to the new workspace. Suggest simplification to avoid confusion.
-# Switch to production environment -terraform workspace new production -terraform workspace select production +# Create and switch to production environment +terraform workspace new production +# (Later) Switch to an existing workspace +# terraform workspace select productiondocs/guides/local-database-setup.mdx (4)
13-58: Step icon removal: mirror in nested code blocks (optional)Drop code-block icons to keep a uniform, minimal layout.
-```yaml title="docker-compose.yml" icon="docker" +```yaml title="docker-compose.yml" @@ -```bash title=".env" icon="shield-check" +```bash title=".env" @@ -```bash title="Start Database" icon="play" +```bash title="Start Database" @@ -```bash title="Verify Database" icon="check-circle" +```bash title="Verify Database"
60-89: Consistency: remove code-block icons within this Step (optional)Matches the icon-less Step header.
-```bash title="Open Suga Editor" icon="edit" +```bash title="Open Suga Editor" @@ -```yaml title="suga.yaml" icon="file-code" +```yaml title="suga.yaml"
91-122: Consistency: remove code-block icons (optional)Keep visuals consistent across Steps.
-```sql title="init.sql" icon="database" +```sql title="init.sql" @@ -```bash title="Reset Database with Schema" icon="refresh-cw" +```bash title="Reset Database with Schema"
124-141: Consistency: remove code-block icons (optional)Same rationale here.
-```bash title="Test Direct Connection" icon="database" +```bash title="Test Direct Connection" @@ -```bash title="Start Your Application" icon="rocket" +```bash title="Start Your Application"docs/cli/templates.mdx (1)
19-22: Align example with surrounding copyThe page says “Shows available templates with descriptions,” but the example list has no descriptions. Either add short descriptions per template or update the sentence above to remove that claim.
You could revise the earlier line (outside this hunk) to:
Shows available templates to help you choose the right starting point.docs/cli/edit.mdx (1)
6-6: Use imperative voice for command docsChange “Edits an application…” to “Edit an application…” for consistency with other CLI pages.
-Edits an application using the suga.yaml application spec and referenced platform. +Edit an application using the suga.yaml application spec and referenced platform.docs/cli/access-token.mdx (2)
3-3: Minor grammar tweakAdd an article for readability.
-description: 'Get access token' +description: 'Get an access token'
14-17: Show refresh usage and caution about outputAdd an example with -r and a brief note to avoid leaking tokens in logs.
Example snippet (outside this hunk):
suga access-token -r # Retrieves a new token, bypassing cacheAnd a short note:
“Note: Treat tokens as secrets; avoid committing or logging them.”docs/cli/login.mdx (3)
3-6: Use “Log in” (verb) consistentlyPrefer “Log in to Suga” and “Log in to the Suga CLI” for consistency with standard usage.
-description: 'Login to Suga' +description: 'Log in to Suga' ... -Login to the Suga CLI. +Log in to the Suga CLI.
12-19: Clarify storage details (optional)If possible, specify where credentials are stored (path or OS-specific location) and that they’re encrypted, or link to a security note.
27-29: Fix verb forms in the noteUse “log in”/“log out” as verbs.
-You'll need to login before using most Suga CLI commands. Your session will remain active until you explicitly logout or the session expires. +You'll need to log in before using most Suga CLI commands. Your session will remain active until you explicitly log out or the session expires.docs/cli/installation.mdx (4)
8-15: Surface the login step immediately after install.Early Access requires auth. Add an explicit “Authenticate” step right after Verify to reduce confusion.
## Verify Installation ```bash suga version
+## Authenticate
+
+bash +suga login +--- `31-33`: **Add a short security note for curl | sh installs.** A one-liner reminding users to review the script or verify checksums would be helpful. ```diff <Tab title="Linux"> ```bash curl -sSL https://addsuga.com/install.sh | sh ``` </Tab> @@ <Tab title="Linux"> ```bash curl -sSL https://addsuga.com/install.sh | sh ``` </Tab> + <Note> + For security, review the install script before running or verify its checksum. + </Note>Also applies to: 58-59
39-41: Confirm deprecation/alias of --version.If
suga --versionstill works, consider noting both forms for discoverability; if deprecated, add a brief note.
63-80: Clarify Web UI auth and behavior of suga edit.State that opening the editor may prompt for login (Early Access) and that the command opens a browser but continues using the local CLI context.
## Web UI @@ -Access it through the CLI: +Access it through the CLI (you may be prompted to log in): @@ -This opens the visual editor in your browser and connects it to your local CLI, with the full platform features available at [app.addsuga.com](https://app.addsuga.com). +This opens the visual editor in your browser and connects it to your local CLI session. Full platform features are available at [app.addsuga.com](https://app.addsuga.com).docs/cli/init.mdx (2)
6-15: Note idempotency/overwrites and prerequisites.Briefly state whether running init overwrites an existing suga.yaml (or requires --force) and whether login is required during Early Access.
16-24: Cross-link the suga.yaml reference.If a dedicated page exists, link to it to help users understand what gets created.
-This creates the necessary Suga configuration files (`suga.yaml`) to transform your existing application into a Suga project, allowing you to define and manage cloud infrastructure alongside your code. +This creates the necessary Suga configuration files (`suga.yaml`) to transform your existing application into a Suga project, allowing you to define and manage cloud infrastructure alongside your code. See the [`suga.yaml` reference](/reference/suga-yaml) for details.docs/cli/new.mdx (3)
12-19: Call out template discovery.Since the page emphasizes templates, add a one-liner pointing users to list templates with
suga templates.The command creates a new directory with your project name, including: @@ - Example infrastructure setup + +List available templates with: +```bash +suga templates +```
32-38: Add missing JavaScript example for completeness.JS is supported per generate docs; include it here too.
# Create project with default template suga new my-app @@ # Force overwrite existing directory suga new my-app --force + +# (Optional) Create with a JavaScript template interactively +# suga templates # choose a JS template +# suga new my-js-app
40-42: Mirror the “Alternative” cross-link phrasing used in init.mdx.Keep the two pages symmetric so users can quickly choose the right path.
docs/cli/logout.mdx (2)
12-19: Clarify server-side vs local revocation.State whether tokens/sessions are invalidated server-side or only removed locally, and any impact on active Web UI sessions.
26-28: Consistency: “log in” vs “login.”If following a style guide, prefer “log in” (verb) and keep “login” for the command/name. Otherwise, standardize across the docs.
docs/cli/build.mdx (3)
12-20: Be explicit about what “Generates Terraform” includes.Does build also build/push container images, or only generate infra code? Add a line clarifying artifacts and side effects.
21-28: Tighten Output Structure wording and align with actual directory shape.Confirm the exact on-disk path and whether images are produced locally or referenced by tag. If the provider list is dynamic, avoid hardcoding.
-The build process creates a `.suga/stacks/` directory containing: -- **Terraform configuration** - Cloud provider resources (AWS, GCP, Azure) -- **Application containers** - Services, built into Docker Containers ready for deployment +The build process creates a `.suga/stacks/` directory (per stack) containing: +- **Terraform configuration** - Cloud provider resources (e.g., AWS, GCP, Azure) +- **Application containers** - Service image definitions (and, if applicable, built images/tags)
31-35: Add cross-links and flags for non-interactive builds.If
suga buildaccepts provider/region flags (for CI), document them and link tosuga configfor defaults.docs/cli/generate.mdx (3)
14-19: State requirement when no language flags are provided.Document whether at least one language flag is mandatory and what the default behavior is.
20-26: Document defaults for output paths and package names.If omitted, where do clients get generated and what package/module names are used?
29-41: Add JavaScript example and an overwrite note.JS is listed but not exemplified; include it. Also note whether generation overwrites existing files or requires a flag.
```bash # Generate TypeScript client suga generate --ts --ts-out ./client @@ # Generate Python client suga generate --python --python-out ./python-client + +# Generate JavaScript client +suga generate --js --js-out ./js-client @@ # Generate multiple clients at once suga generate --ts --ts-out ./ts-client --go --go-out ./go-client --go-package-name suga
+
- Generation may overwrite existing files in the output directory. Commit or back up changes before regenerating.
+</blockquote></details> <details> <summary>docs/cli/introduction.mdx (3)</summary><blockquote> `26-42`: **Minor table polish and parity check.** - “autocompletion” vs “autocomplete”: pick one globally. - Ensure every listed command has a corresponding page (e.g., `team`, `access-token`) and that names/descriptions match CLI help. --- `45-64`: **Include Access Token in “Team Authentication” card.** Users often need both login and access-token; mention both for quicker discovery. ```diff <Card title="Team Authentication" icon="key" href="/cli/login"> - Use `suga login` to connect to Suga Platform + Use `suga login` to connect to Suga Platform and `suga access-token` to retrieve tokens for tools/CI </Card>
12-22: Add login to Quick Start (Early Access).Reflect the requirement introduced on the Installation page.
```bash # Install the CLI brew install nitrictech/tap/suga +# Authenticate (Early Access) +suga login + # Create a new project suga new my-app
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (17)
docs/cli/access-token.mdx(1 hunks)docs/cli/build.mdx(1 hunks)docs/cli/dev.mdx(1 hunks)docs/cli/edit.mdx(2 hunks)docs/cli/generate.mdx(1 hunks)docs/cli/init.mdx(1 hunks)docs/cli/installation.mdx(3 hunks)docs/cli/introduction.mdx(1 hunks)docs/cli/login.mdx(1 hunks)docs/cli/logout.mdx(1 hunks)docs/cli/new.mdx(1 hunks)docs/cli/templates.mdx(1 hunks)docs/docs.json(1 hunks)docs/guides/local-database-setup.mdx(4 hunks)docs/guides/overview.mdx(1 hunks)docs/guides/terraform-backend-config.mdx(2 hunks)docs/index.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-27T03:55:50.432Z
Learnt from: davemooreuws
PR: nitrictech/suga#29
File: docs/guides/terraform-backend-config.mdx:25-34
Timestamp: 2025-08-27T03:55:50.432Z
Learning: In the Suga project, the default directory for CDKTF synthesized output is `terraform/`, not `cdktf.out/`. The directory structure is terraform/stacks/<stack_name>/ containing the generated Terraform configurations.
Applied to files:
docs/guides/terraform-backend-config.mdx
🔇 Additional comments (9)
docs/guides/terraform-backend-config.mdx (1)
48-54: Path matches Suga’s CDKTF outputUsing terraform/stacks/<stack_name>/ aligns with our recorded default output location. Nice.
docs/guides/overview.mdx (1)
44-44: Support email change looks goodAddress matches other pages (docs.json navbar and index.mdx). No further action.
docs/docs.json (1)
25-25: Confirm new nav target exists and buildsEnsure docs/cli/installation.mdx is present and included in the build so this nav item doesn’t 404.
docs/index.mdx (1)
71-71: Consistent support addressUpdated mailto uses addsuga.com and matches other docs. LGTM.
docs/cli/templates.mdx (1)
19-22: Verify template slugsPlease confirm these identifiers exactly match what
suga templatesoutputs (including hyphens and casing), so users can copy-paste reliably.docs/cli/edit.mdx (1)
24-24: Editor URL update looks correctDomain matches the rest of the rebrand.
docs/cli/dev.mdx (1)
6-6: Confirm feature claimsIntro now emphasizes “local testing of resources,” while the Features still list “Hot reloading.” Please verify both are supported by
suga devand adjust wording if needed.docs/cli/installation.mdx (1)
20-33: Validate package sources (brew/scoop/script) are current.Please confirm the Homebrew tap, Scoop bucket URL, and install script endpoint are still the recommended sources for vNext of the CLI. If #49 changes these, update here too.
Also applies to: 52-59
docs/cli/new.mdx (1)
26-29: Confirm options parity with CLI help.If
--template(or similar) was removed, ensure the CLI help aligns and the removal is intentional.
|
🎉 This PR is included in version 0.0.5 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
4 participants
wait for #49