Improve tooling and documentation by bubacoder · Pull Request #229 · bubacoder/infra

bubacoder · 2025-11-22T09:24:19Z

Summary by CodeRabbit

Documentation
- Improved clarity, grammar, punctuation, links and terminology across READMEs, setup guides and runbooks.
- Added a documentation-improvement workflow to automate linting, fixes and QA for Markdown content.
Chores
- Updated container image to v3.6.2.
- Added/adjusted development environment and linting configurations and editor workspace settings.
- Expanded allowed script actions in local tooling permissions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2025-11-22T09:24:27Z

Walkthrough

Adds an AI-driven Markdown documentation improvement workflow and workspace settings; introduces flake8 and pre-commit adjustments; updates Traefik image tag and a script path; and applies minor grammar, wording, link, and formatting fixes across multiple docs.

Changes

Cohort / File(s)	Summary
AI Documentation Workflow & Configuration `.claude/commands/improve-docs.md`, `.claude/settings.json`	Adds a markdown-focused documentation improvement workflow with analysis, fix, QA, and summary steps; adds a Bash allow entry (`Bash(scripts/labctl.py service logs:*)`) to `.claude/settings.json`.
Linting & Pre-commit Configuration `.flake8`, `.pre-commit-config.yaml`	Adds `.flake8` ignoring E501 (line too long); fixes comment typo ("pendling" → "pending") and adjusts ansible-lint pinned rev from v25.11.0 → v25.9.0.
IDE & Workspace Settings `.vscode/settings.json`	Adds VSCode workspace settings disabling Copilot and configuring SpellRight for English on markdown/latex/plaintext.
Top-level Documentation Edits `AGENTS.md`, `README.md`	Minor punctuation, capitalization, and phrasing edits for clarity and consistency.
Nested Documentation Edits `ansible/README.md`, `docker/README.md`, `docs/ai/README.md`, `docs/runbooks.md`, `docs/setup.md`	Typo fixes, link target correction, terminology and capitalization standardization (e.g., "devcontainer" → "Dev Container"), and prose improvements; some file path example updates.
Infra & Script Changes `docker/security/traefik.yaml`, `scripts/copy-repo-template.sh`	Bumps Traefik image tag v3.6.0 → v3.6.2; updates copy target in script from `../../repo-template` → `../repo-template`.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Workflow as Improve-Docs Workflow
  participant Repo as Repository Files
  participant Linter as QA/Lint Tools
  participant Summary

  rect rgba(0,128,96,0.06)
    User->>Workflow: Trigger with FILES arg
    Workflow->>Repo: Identify Markdown files
    Workflow->>Repo: Read file contents
    Workflow->>Repo: Analyze for spelling/grammar/style/links
    Workflow->>Repo: Apply non-destructive fixes
  end

  rect rgba(0,96,192,0.06)
    Workflow->>Linter: Run linting/docs checks
    Linter-->>Workflow: Report issues
    Workflow->>Repo: Re-apply fixes if needed
  end

  rect rgba(192,96,0,0.06)
    Workflow->>Summary: Produce modified-files list and notes
    Summary-->>User: Output report of changes
  end

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Review points:
- Verify scripts/copy-repo-template.sh path change aligns with repository layout.
- Confirm ansible-lint rev downgrade (v25.11.0 → v25.9.0) and compatibility implications.
- Spot-check docs/setup.md edits for any unintended technical alterations.

Possibly related PRs

Add git repo template script #216: Modifies scripts/copy-repo-template.sh — directly related to the same script path change in this PR.
Initialize Claude Code #156: Touches .claude/settings.json — overlaps with permission entries changed here.
Fix line ending and devcontainer issue on Windows, add pipx #159: Updates docs/setup.md and devcontainer docs — overlaps with setup documentation edits in this PR.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Improve tooling and documentation' accurately reflects the changeset, which includes tooling updates (flake8, .pre-commit-config.yaml, .claude/settings.json, VSCode settings, Traefik version bump, copy script path fix) and documentation improvements (README files, docs, AGENTS.md).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feature/fix-tools

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (4)

.flake8 (1)
1-2: Clarify line‑length policy across linters

Right now E501 is fully ignored, which is fine if you don’t want flake8 enforcing line length, but it can diverge from whatever Ruff or other tools enforce for max line length.

If you still want a soft cap while avoiding noisy false positives, consider configuring an explicit max-line-length and only ignoring E501 where needed, so tools stay aligned:
 [flake8]
-extend-ignore = E501 # Line too long
+extend-ignore = E501  # Line too long (generally handled elsewhere)
+# Example, if you still want a guideline:
+# max-line-length = 100
Adjust or drop max-line-length to match your actual standard.
docs/setup.md (2)

44-44: Consider replacing weak adjective "quite" for stronger phrasing.

Line 44 uses "quite large" to describe the container image size. LanguageTool suggests this is a weak intensifier. Consider using more specific language, such as:

"The resulting container image is substantial (4+ GB)..."

"The resulting container image is large (4+ GB)..."

"The resulting container image exceeds 4 GB..."

107-109: TODO items should be tracked separately.

Lines 107-109 and 135-137 contain TODO comments about missing documentation sections. While these acknowledge incomplete work, consider:

Opening GitHub issues to track these documentation gaps

Using a more structured tracking mechanism (e.g., GitHub Projects)

This ensures visibility and helps prioritize future documentation work.

Would you like me to help identify and open GitHub issues for these TODO items?

Also applies to: 135-137
.claude/commands/improve-docs.md (1)
35-35: Capitalize "Markdown" for consistency with proper noun conventions.

Line 35 references "markdown formatting." Per standard style conventions and LanguageTool, the word "Markdown" should be capitalized as it is a proper noun (the name of the markup language).

Apply this minor fix:
-   - Ensure consistent markdown formatting
+   - Ensure consistent Markdown formatting

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 802d5e8 and e5bcff4.

📒 Files selected for processing (14)

.claude/commands/improve-docs.md (1 hunks)
.claude/settings.json (1 hunks)
.flake8 (1 hunks)
.pre-commit-config.yaml (2 hunks)
.vscode/settings.json (1 hunks)
AGENTS.md (1 hunks)
README.md (2 hunks)
ansible/README.md (1 hunks)
docker/README.md (1 hunks)
docker/security/traefik.yaml (1 hunks)
docs/ai/README.md (1 hunks)
docs/runbooks.md (1 hunks)
docs/setup.md (5 hunks)
scripts/copy-repo-template.sh (1 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

**/*.sh

📄 CodeRabbit inference engine (AGENTS.md)

Shell scripts must pass ShellCheck linting

Files:

scripts/copy-repo-template.sh

.pre-commit-config.yaml

📄 CodeRabbit inference engine (AGENTS.md)

Contributors must follow the pre-commit rules defined in .pre-commit-config.yaml

Files:

.pre-commit-config.yaml

**/*.{yml,yaml}

📄 CodeRabbit inference engine (AGENTS.md)

All YAML files must be linted and validated

Files:

docker/security/traefik.yaml

{terraform/**/*.tf,docker/**/*.{yml,yaml}}

📄 CodeRabbit inference engine (AGENTS.md)

Run KICS security scanning on IaC files (Terraform and Docker Compose)

Files:

docker/security/traefik.yaml

docker/**/*.{yml,yaml}

📄 CodeRabbit inference engine (AGENTS.md)

Define each Docker service in a YAML file within the appropriate category under docker/

Files:

docker/security/traefik.yaml

🧠 Learnings (6)