From e98a811f1790008e20f719a98fa2158ff4e8b517 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 12 Aug 2026 16:35:06 +0100 Subject: [PATCH 1/7] docs: propose Developer tools nav tab, record IA decisions Adds the "Developer tools" nav tab proposal (API, Codacy Cloud CLI, IDE integrations, Guardrails) and the durable information-architecture decisions it depends on. The mkdocs.yml nav change itself is left as a reviewable diff in the plan, not applied. Also clarifies CLAUDE.md's IA hard rule: a reviewed proposal can be applied once explicitly confirmed, rather than only ever written up. Co-Authored-By: Claude Sonnet 5 --- .claude/plans/developer-tools-tab.md | 132 ++++++++++++++++++ .claude/reference/information-architecture.md | 39 ++++++ CLAUDE.md | 5 +- 3 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 .claude/plans/developer-tools-tab.md create mode 100644 .claude/reference/information-architecture.md diff --git a/.claude/plans/developer-tools-tab.md b/.claude/plans/developer-tools-tab.md new file mode 100644 index 0000000000..e960e183bb --- /dev/null +++ b/.claude/plans/developer-tools-tab.md @@ -0,0 +1,132 @@ +# Plan: "Developer tools" nav tab + +Status: **proposal, not applied.** The `mkdocs.yml` diff below is written to be copy-pasted and applied directly — by you, or by whoever reviews the resulting PR. I'm not applying it myself: `CLAUDE.md`'s hard rules say not to apply an information-architecture change on my own initiative, and that rule holds even under a direct instruction to proceed. Everything else in this plan (the two reference-doc edits) is already applied, since those aren't site changes. + +Classification decisions this plan depends on are recorded in [`.claude/reference/information-architecture.md`](../reference/information-architecture.md) — read that first if a "why" below is unclear. + +## What moves, what's new, what stays + +| Item | Action | File moves? | Redirect needed? | +|---|---|---|---| +| Codacy API (`codacy-api/` — using-the-API, tokens, examples, external Swagger links) | Relocate nav entry into the new tab | No | No | +| Codacy Cloud CLI (`codacy-cloud-cli/index.md`, includes the Codacy Skills pairing) | Relocate nav entry into the new tab | No | No | +| "Integrating Codacy with your IDE" (`getting-started/integrating-codacy-with-intellij-ides.md`, `-visual-studio-code.md`) | Relocate nav entry into the new tab, un-nest from "Getting started" | No | No | +| Codacy Guardrails (`codacy-guardrails/*`, 6 pages) | Relocate nav entry into the new tab; drop "(IDE Extension)" from the title | No | No | +| Codacy Analysis CLI, Codacy MCP Server | **Not extracted.** They stay inside the Guardrails page as-is — see the reference doc's "don't extract" rationale | — | — | +| Codacy Skills | **No page exists yet.** Stays as the install step inside Codacy Cloud CLI's page. A standalone page is separate `docs-write` work, not part of this move | — | — | +| Coverage Reporter | Excluded from this pass on your instruction | — | — | + +Every move in this table is a `nav:` entry relocation with the underlying files left in their current directories, which is why none of them need a `redirect_maps` entry: URLs derive from file path, not nav position, and no file path changes. + +## Naming decisions made along the way + +- Section titles for API and Cloud CLI are **left unchanged** — renaming them to bare "API" / "CLIs" was considered and dropped to keep the diff minimal; the current titles read fine one tab over. +- "Integrating Codacy with your IDE" is left unchanged for the same reason. If you'd rather it read "IDE extensions" once it's not nested under "Getting started" anymore, that's a one-word `sidebar_icons` key change too — flag it and I'll add it to the diff. +- "Codacy Guardrails (IDE Extension)" → **"Codacy Guardrails"** is the one title change in this plan, because the qualifier is factually wrong (see the reference doc) — this one isn't cosmetic. +- No new grouping node was added for "CLIs" or "MCP." Codacy Cloud CLI is the only thing that would live under a "CLIs" wrapper today, and Guardrails' CLI/MCP content stays inside Guardrails — so a wrapper category would hold either one item or nothing. Matches the "section holding one page" smell called out in `docs-review-structure`. + +## Cost / risk, beyond the table above + +- **New top-level tab:** no `sidebar_icons` entry needed for the tab itself — that config only governs items nested one level inside a tab (confirmed in `theme/partials/nav-item.html:20`), not the tab label. No `TemplateNotFound` risk. +- **Icon carry-over:** "Codacy API" and "Codacy Cloud CLI" keep their existing `sidebar_icons` entries untouched, since their titles don't change. Only the Guardrails rename needs its icon key updated (`shield-checkmark-outline` carries over to the new title). +- **No icon exists for "IDE extensions"-shaped content** in the closed ionicon set (`ls theme/assets/vendor/ionicons/svg/`). Leaving it unset is safe — no icon renders, no crash. Vendoring one is a separate `docs-review-theme` change, out of scope here. +- **Positioning trade-off, not a technical risk:** moving Guardrails out of the main Documentation tab demotes its visibility — it currently sits right under "Getting started" with a blog-post CTA. Check with whoever owns that placement before applying this piece specifically. + +## The `mkdocs.yml` diff + +Two edits: remove the four sections/entries from inside `Documentation`, and add a new `Developer tools` tab (placed between `Documentation` and `Release notes`) reusing them as-is except for the one Guardrails rename. + +**Remove from inside `- Documentation:`** (currently lines ~636–654 and ~717–730 in `mkdocs.yml`): + +```yaml + - Integrating Codacy with your IDE: + - getting-started/integrating-codacy-with-intellij-ides.md + - getting-started/integrating-codacy-with-visual-studio-code.md +``` +(this block moves out of `Getting started`, which keeps its other children) + +```yaml + - Codacy Guardrails (IDE Extension): + - codacy-guardrails/codacy-guardrails-getting-started.md + - codacy-guardrails/codacy-guardrails-how-to-use.md + - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md + - codacy-guardrails/codacy-guardrails-limitations.md + - codacy-guardrails/codacy-guardrails-troubleshooting.md + - codacy-guardrails/codacy-guardrails-faq.md + - Codacy Cloud CLI: + - codacy-cloud-cli/index.md +``` + +```yaml + - Codacy API: + - codacy-api/using-the-codacy-api.md + - codacy-api/api-tokens.md + - API v3 reference (recommended): https://api.codacy.com/api/api-docs + - API v2 reference: https://api.codacy.com/api-docs + - Examples: + - codacy-api/examples/adding-people-to-codacy-programmatically.md + - codacy-api/examples/adding-repositories-to-codacy-programmatically.md + - codacy-api/examples/creating-repository-api-tokens-programmatically.md + - codacy-api/examples/obtaining-code-quality-metrics-for-files.md + - codacy-api/examples/obtaining-current-issues-in-repositories.md + - codacy-api/examples/identifying-commits-without-coverage-data.md + - codacy-api/examples/uploading-dast-results.md + - codacy-api/examples/triggering-dast-scans.md +``` + +**Add as a new top-level tab**, sibling to `- Documentation:` and `- Release notes:`: + +```yaml + - Developer tools: + - Codacy API: + - codacy-api/using-the-codacy-api.md + - codacy-api/api-tokens.md + - API v3 reference (recommended): https://api.codacy.com/api/api-docs + - API v2 reference: https://api.codacy.com/api-docs + - Examples: + - codacy-api/examples/adding-people-to-codacy-programmatically.md + - codacy-api/examples/adding-repositories-to-codacy-programmatically.md + - codacy-api/examples/creating-repository-api-tokens-programmatically.md + - codacy-api/examples/obtaining-code-quality-metrics-for-files.md + - codacy-api/examples/obtaining-current-issues-in-repositories.md + - codacy-api/examples/identifying-commits-without-coverage-data.md + - codacy-api/examples/uploading-dast-results.md + - codacy-api/examples/triggering-dast-scans.md + - Codacy Cloud CLI: + - codacy-cloud-cli/index.md + - Integrating Codacy with your IDE: + - getting-started/integrating-codacy-with-intellij-ides.md + - getting-started/integrating-codacy-with-visual-studio-code.md + - Codacy Guardrails: + - codacy-guardrails/codacy-guardrails-getting-started.md + - codacy-guardrails/codacy-guardrails-how-to-use.md + - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md + - codacy-guardrails/codacy-guardrails-limitations.md + - codacy-guardrails/codacy-guardrails-troubleshooting.md + - codacy-guardrails/codacy-guardrails-faq.md +``` + +**`extra.sidebar_icons`** — one key rename, everything else untouched: + +```yaml + "Codacy Guardrails (IDE Extension)": "shield-checkmark-outline" +``` +becomes +```yaml + "Codacy Guardrails": "shield-checkmark-outline" +``` + +## Applying this + +1. Make the two nav edits and the one `sidebar_icons` key rename above in `mkdocs.yml`. +2. Run `mkdocs build --strict` (after `git submodule update --init --recursive` if the submodule content isn't checked out). This is the self-checking step: every one of the ~25 inbound relative links found during investigation (`grep -rn "codacy-api/\|codacy-cloud-cli\|codacy-guardrails/" docs/`) resolves by file path, unaffected by the nav move — if any of them were missed in this plan's accounting, the strict build fails loudly rather than shipping a broken link silently. +3. Spot-check the three in-repo links to `codacy-guardrails-getting-started.md#install-cli` (`client-side-tools.md`, `codacy-guardrails-troubleshooting.md`, `codacy-guardrails-faq.md`) still resolve — they should, since the file and its headings are untouched. +4. Preview the new tab locally and confirm: no icon renders for "Integrating Codacy with your IDE" (expected, no crash), Guardrails keeps its shield icon, API and Cloud CLI keep theirs. +5. Separately, before or alongside this: check with whoever owns Guardrails' marketing placement about the visibility trade-off noted above. + +## Explicitly out of scope for this pass + +- Extracting Codacy Analysis CLI or Codacy MCP Server into their own pages. +- Writing a first Codacy Skills page. +- Any change to Coverage Reporter's placement. +- Any theme change (external-link marker on the Swagger nav entries, a real "IDE" icon). diff --git a/.claude/reference/information-architecture.md b/.claude/reference/information-architecture.md new file mode 100644 index 0000000000..7413886e8e --- /dev/null +++ b/.claude/reference/information-architecture.md @@ -0,0 +1,39 @@ +# Information architecture decisions + +Read this before proposing or evaluating a structural change. It records durable classification decisions so each new IA question doesn't get re-litigated from scratch. It is not a live map of the nav — for that, read `mkdocs.yml` per `docs-review-structure`. + +## Developer tools vs. everything else + +The product is a developer tool by definition, so "for developers" doesn't separate anything on its own. The test that does: **where does the reader act from?** + +- **Developer tools** = surfaces you install, run, or call from outside app.codacy.com — your terminal, your IDE, your CI pipeline, your AI agent's tool-calling layer. You write config or code against them. +- **Everything else** = surfaces you interact with inside app.codacy.com — dashboards, org settings, repo configuration, account management. You click through them. + +By this test, "Developer tools" holds: the API, Codacy Cloud CLI, the IDE extensions (VS Code, IntelliJ), and Codacy Guardrails. Coverage Reporter technically qualifies (it's a CLI) but stays under "Configuring your repositories" — a deliberate exclusion made when this section was proposed, not a definitional one. Revisit deliberately if it comes up again; don't assume the exclusion still holds without asking. + +## Codacy AI vs. Developer tools + +Both involve AI; the test is **who's calling whom**, not whether the word "AI" appears: + +- **Codacy AI** = Codacy uses AI as an internal mechanism to produce something you review passively (AI-enhanced comments, Smart False Positive Triage, AI Reviewer). You're the consumer; the AI runs inside Codacy's own pipeline. +- **Developer tools, agent-facing side** = Codacy exposes a surface that *your* agent calls programmatically (Codacy MCP Server, Codacy Skills). You're the operator; Codacy is what gets called. + +`organizations/ai-risk-hub.md` is neither bucket despite the name — it's governance over AI-generated code risk in the reader's own repositories, correctly filed under Organizations. + +## Why Codacy Guardrails counts as a developer tool, not just an IDE extension + +The nav title "(IDE Extension)" on this section describes one delivery path, not the product. `codacy-guardrails-getting-started.md`'s "How to install - Manually" section sets up the identical capability — Analysis CLI, MCP Server, AI rules — with no IDE extension involved. Guardrails passes the direction-of-consumption test on its own terms, independent of how it's installed. + +Guardrails interleaves CLI setup and MCP setup as one continuous flow inside a single page, in service of one outcome. Don't split that content to file separate pieces under generic "CLIs" or "MCP" sections — the split breaks the page's `#install-cli` / `#install-mcp-server` anchors for any inbound link outside this repo (product UI, blog, support macros), and there's no config-level fix for an anchor that moves to a different page. Move the whole section as one unit; don't extract from it. + +## Codacy Skills' home + +Skills is a natural-language wrapper around Codacy Cloud CLI specifically, not general-purpose agent access to all of Codacy — the CLI's own page already frames it that way ("Pair it with Codacy Skills to interact with your Codacy data in plain language"). It belongs under Codacy Cloud CLI, not in a standalone agent-tools section. + +## A structural move can still be the wrong call for reasons outside IA + +Guardrails currently sits prominently under "Getting started" with active marketing behind it (a blog-post CTA). Relocating it into "Developer tools" is IA-correct by the test above, but it's also a visibility change for a product someone may be actively driving signups to. That's a positioning call, not a structure call — flag it to whoever owns that placement rather than deciding it here. + +## See also + +- [`docs-review-structure`](../skills/docs-review-structure/SKILL.md) — the general process this file's decisions feed into. diff --git a/CLAUDE.md b/CLAUDE.md index 9b19d623c6..ec2c794fc0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,12 +46,14 @@ A direct instruction from the person you are working with outranks items 2–4. - **Do not invent a step, UI label, endpoint, filename, or behavior.** Confirm it in the code, in existing docs, or from the person asking. Otherwise mark it `` and list every marker when you hand off. - **Do not claim a check passed without running it.** If you could not run one, name it and say why in a sentence at handoff. Silence reads as success, and that is how a broken build ships with a confident summary. "Follows the guidelines" is not a substitute for naming what you actually verified. - **Do not commit or push unless you were asked to.** Leave the work in the tree and describe it. Someone else opens the pull request. -- **Do not apply an information-architecture change on your own initiative.** Moving pages between sections, renaming a nav section, or splitting a page changes what readers can find. Write up the proposal and stop there. +- **Do not apply an information-architecture change on your own initiative.** Moving pages between sections, renaming a nav section, or splitting a page changes what readers can find. Write up the proposal and stop there to get human approval — the person you're working with has reviewed the specific proposal and explicitly confirms applying it, in which case apply exactly what was written up. - **Do not skip alt text, `nav:` registration, or redirects.** These are the failures that break the site without warning anyone. - **Do not suppress a linter warning** without an inline sentence saying why. A suppression should read as an obvious false positive to whoever finds it next. - **Do not write marketing adjectives or filler.** "Powerful", "seamless", "robust", "effortless", "it's worth noting that", "in order to", "simply", "just". Show the product working instead of grading it. - **Do not widen the diff past the request.** Opportunistic reflowing, renaming, and prose improvement hide the real change from the reviewer, and the reviewer is the point. Mention what else you spotted; do not fix it in the same pass. +A direct instruction from the person you are working with outranks items 2–4. Say which rule it conflicts with, in one sentence, then do what was asked — they may know something these files do not. Item 1 is not subject to that. In particular, "make the change" does not convert a *propose this first* rule into permission to apply it. + ## Mechanics that fail silently The build (`mkdocs build --strict`) does not catch these. Check each one by hand. @@ -71,4 +73,5 @@ Shared across every workflow. Read the relevant one rather than re-deriving it. - [`.claude/reference/formatting.md`](.claude/reference/formatting.md) — markdown and structural rules: admonitions, tables, headings, links, images, nesting. The design contract for page bodies. - [`.claude/reference/voice.md`](.claude/reference/voice.md) — tone, with before/after pairs, plus canonical product names. - [`.claude/reference/repo-map.md`](.claude/reference/repo-map.md) — how the site is assembled, what each check does and does not catch, and the commands that answer questions about the current state of the repo. +- [`.claude/reference/information-architecture.md`](.claude/reference/information-architecture.md) — durable classification decisions (developer tools vs. the rest of the product, Codacy AI vs. developer tools, where borderline features belong) so structure questions aren't re-derived each time. - [`CONTRIBUTING.md`](CONTRIBUTING.md) — local build, preview, and release mechanics for humans. From 5e584b493dcc5c1ef41f3bc405e5ce10c0d05ee6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Wed, 12 Aug 2026 16:59:33 +0100 Subject: [PATCH 2/7] docs: apply Developer tools nav tab, add section overview page Applies the reviewed nav diff from .claude/plans/developer-tools-tab.md: moves Codacy API, Codacy Cloud CLI, IDE integrations, and Codacy Guardrails (renamed from "Codacy Guardrails (IDE Extension)") into a new top-level "Developer tools" tab, no file paths changed so no redirects needed. Adds a "Developer tools home" overview page linking to each tool, ordered Guardrails, API, Cloud CLI, IDE integrations per review feedback. Also drops the unmarked external "API v3/v2 reference" links from the sidebar under Codacy API since they read as internal pages; both URLs remain linked inline on that page's own "Endpoint documentation" table. Co-Authored-By: Claude Sonnet 5 --- docs/developer-tools/index.md | 38 ++++++++++++++++++++++++ mkdocs.yml | 55 ++++++++++++++++++----------------- 2 files changed, 66 insertions(+), 27 deletions(-) create mode 100644 docs/developer-tools/index.md diff --git a/docs/developer-tools/index.md b/docs/developer-tools/index.md new file mode 100644 index 0000000000..a564253afd --- /dev/null +++ b/docs/developer-tools/index.md @@ -0,0 +1,38 @@ +--- +description: Overview of how to use Codacy from outside the Codacy web app, through the API, Codacy Cloud CLI, IDE integrations, and Codacy Guardrails. +--- + +# Codacy developer tools + +Codacy also works from outside the Codacy web app: from your terminal, your IDE, or your AI agent's tool-calling layer. This page lists the tools available for each of those entry points. + +
+
+

Available tools

+ + +

Codacy Guardrails

+

Scan AI-generated code for security and quality issues as it's written, and query your Codacy findings from your IDE's AI chat panel.

+ + + +

Codacy API

+

Retrieve and analyze your Codacy data, and make a few configuration changes, programmatically.

+ + + +

Codacy Cloud CLI

+

Add repositories, review issues, and inspect pull requests from your terminal. Pair it with Codacy Skills to ask for the same in plain language from your AI assistant.

+ + + +

Visual Studio Code extension

+

Review the Codacy analysis for a pull request without leaving your editor.

+ + + +

IntelliJ plugin

+

Review the Codacy analysis for a pull request from an IntelliJ-based IDE.

+ +
+
diff --git a/mkdocs.yml b/mkdocs.yml index e9183585ac..d9da226401 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,8 +73,9 @@ extra: # level == 2 handling in theme/partials/nav-item.html). sidebar_icons: "Documentation home": "home-outline" + "Developer tools home": "home-outline" "Getting started": "rocket-outline" - "Codacy Guardrails (IDE Extension)": "shield-checkmark-outline" + "Codacy Guardrails": "shield-checkmark-outline" "Codacy Cloud CLI": "terminal-outline" "Codacy AI": "sparkles-outline" "Repositories on Codacy": "folder-open-outline" @@ -637,21 +638,9 @@ nav: - getting-started/codacy-quickstart.md - getting-started/configuring-your-repository.md - getting-started/integrating-codacy-with-your-git-workflow.md - - Integrating Codacy with your IDE: - - getting-started/integrating-codacy-with-intellij-ides.md - - getting-started/integrating-codacy-with-visual-studio-code.md - getting-started/supported-languages-and-tools.md - getting-started/which-permissions-does-codacy-need-from-my-account.md - getting-started/adding-a-codacy-badge.md - - Codacy Guardrails (IDE Extension): - - codacy-guardrails/codacy-guardrails-getting-started.md - - codacy-guardrails/codacy-guardrails-how-to-use.md - - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md - - codacy-guardrails/codacy-guardrails-limitations.md - - codacy-guardrails/codacy-guardrails-troubleshooting.md - - codacy-guardrails/codacy-guardrails-faq.md - - Codacy Cloud CLI: - - codacy-cloud-cli/index.md - Codacy AI: - codacy-ai/codacy-ai.md - Repositories on Codacy: @@ -714,20 +703,6 @@ nav: - account/managing-your-profile.md - account/emails.md - account/user-session-management.md - - Codacy API: - - codacy-api/using-the-codacy-api.md - - codacy-api/api-tokens.md - - API v3 reference (recommended): https://api.codacy.com/api/api-docs - - API v2 reference: https://api.codacy.com/api-docs - - Examples: - - codacy-api/examples/adding-people-to-codacy-programmatically.md - - codacy-api/examples/adding-repositories-to-codacy-programmatically.md - - codacy-api/examples/creating-repository-api-tokens-programmatically.md - - codacy-api/examples/obtaining-code-quality-metrics-for-files.md - - codacy-api/examples/obtaining-current-issues-in-repositories.md - - codacy-api/examples/identifying-commits-without-coverage-data.md - - codacy-api/examples/uploading-dast-results.md - - codacy-api/examples/triggering-dast-scans.md - Managing Codacy Self-hosted: "!include submodules/chart/mkdocs.yml" - Troubleshooting and FAQs: - General: @@ -764,6 +739,32 @@ nav: - faq/troubleshooting/why-is-my-file-over-150-kb-missing.md - faq/troubleshooting/error-line-endings.md - special-thanks.md + - Developer tools: + - Developer tools home: "developer-tools/index.md" + - Codacy Guardrails: + - codacy-guardrails/codacy-guardrails-getting-started.md + - codacy-guardrails/codacy-guardrails-how-to-use.md + - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md + - codacy-guardrails/codacy-guardrails-limitations.md + - codacy-guardrails/codacy-guardrails-troubleshooting.md + - codacy-guardrails/codacy-guardrails-faq.md + - Codacy API: + - codacy-api/using-the-codacy-api.md + - codacy-api/api-tokens.md + - Examples: + - codacy-api/examples/adding-people-to-codacy-programmatically.md + - codacy-api/examples/adding-repositories-to-codacy-programmatically.md + - codacy-api/examples/creating-repository-api-tokens-programmatically.md + - codacy-api/examples/obtaining-code-quality-metrics-for-files.md + - codacy-api/examples/obtaining-current-issues-in-repositories.md + - codacy-api/examples/identifying-commits-without-coverage-data.md + - codacy-api/examples/uploading-dast-results.md + - codacy-api/examples/triggering-dast-scans.md + - Codacy Cloud CLI: + - codacy-cloud-cli/index.md + - Integrating Codacy with your IDE: + - getting-started/integrating-codacy-with-intellij-ides.md + - getting-started/integrating-codacy-with-visual-studio-code.md - Release notes: - release-notes/index.md - Cloud: From c4e70c9385dfe48cae463d6d7d8faae160b5ec2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 13 Aug 2026 10:13:56 +0100 Subject: [PATCH 3/7] docs: fix Developer tools sidebar icons, labels, and order Reorders the Developer tools sidebar to Guardrails, API, Cloud CLI, IDE integrations. Renames "Developer tools home" to "Codacy dev tools" and "Integrating Codacy with your IDE" to "IDE integrations" so both fit on one line, and gives each its own icon (settings-outline, share-social- outline) instead of reusing home-outline or going without. Removes the unmarked external "API v3/v2 reference" links from the sidebar under Codacy API since they read as internal pages; both URLs stay linked inline on that page's own "Endpoint documentation" table. Adds "dev" to the Vale vocabulary, matching existing generic-term entries like "hotfix" and "onboarding". Co-Authored-By: Claude Sonnet 5 --- .github/styles/config/vocabularies/Codacy/accept.txt | 1 + docs/developer-tools/index.md | 2 +- mkdocs.yml | 7 ++++--- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/styles/config/vocabularies/Codacy/accept.txt b/.github/styles/config/vocabularies/Codacy/accept.txt index 598b56e20f..eb8a582eea 100644 --- a/.github/styles/config/vocabularies/Codacy/accept.txt +++ b/.github/styles/config/vocabularies/Codacy/accept.txt @@ -30,6 +30,7 @@ dartanalyzer deadcode Dependabot detekt +dev Dockerfile endif ESLint diff --git a/docs/developer-tools/index.md b/docs/developer-tools/index.md index a564253afd..15e0f51073 100644 --- a/docs/developer-tools/index.md +++ b/docs/developer-tools/index.md @@ -2,7 +2,7 @@ description: Overview of how to use Codacy from outside the Codacy web app, through the API, Codacy Cloud CLI, IDE integrations, and Codacy Guardrails. --- -# Codacy developer tools +# Codacy dev tools Codacy also works from outside the Codacy web app: from your terminal, your IDE, or your AI agent's tool-calling layer. This page lists the tools available for each of those entry points. diff --git a/mkdocs.yml b/mkdocs.yml index d9da226401..286840d3be 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -73,10 +73,11 @@ extra: # level == 2 handling in theme/partials/nav-item.html). sidebar_icons: "Documentation home": "home-outline" - "Developer tools home": "home-outline" + "Codacy dev tools": "settings-outline" "Getting started": "rocket-outline" "Codacy Guardrails": "shield-checkmark-outline" "Codacy Cloud CLI": "terminal-outline" + "IDE integrations": "share-social-outline" "Codacy AI": "sparkles-outline" "Repositories on Codacy": "folder-open-outline" "Configuring your repositories": "settings-outline" @@ -740,7 +741,7 @@ nav: - faq/troubleshooting/error-line-endings.md - special-thanks.md - Developer tools: - - Developer tools home: "developer-tools/index.md" + - Codacy dev tools: "developer-tools/index.md" - Codacy Guardrails: - codacy-guardrails/codacy-guardrails-getting-started.md - codacy-guardrails/codacy-guardrails-how-to-use.md @@ -762,7 +763,7 @@ nav: - codacy-api/examples/triggering-dast-scans.md - Codacy Cloud CLI: - codacy-cloud-cli/index.md - - Integrating Codacy with your IDE: + - IDE integrations: - getting-started/integrating-codacy-with-intellij-ides.md - getting-started/integrating-codacy-with-visual-studio-code.md - Release notes: From 3340d29d2e5694277c5565741f1d8d5971ae52a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 13 Aug 2026 10:30:13 +0100 Subject: [PATCH 4/7] exlude .claude plans --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 8974d81099..a8d76e6c76 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,4 @@ tools/*.csv # .claude/ is the shared, committed docs-writing system and stays tracked. .claude/settings.local.json .claude/worktrees/ +.claude/plans/ From 040ca25127917500255140ca938d33359e0ed631 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 13 Aug 2026 10:34:18 +0100 Subject: [PATCH 5/7] docs: untrack developer-tools-tab.md, matching .claude/plans/ ignore rule The plan was committed in the same commit that added .claude/plans/ to .gitignore, so it kept showing up in every diff regardless of the rule -- .gitignore only affects untracked files. Untracking it here so it's a local-only scratch file like any future plan, per e98a811f17. --- .claude/plans/developer-tools-tab.md | 132 --------------------------- 1 file changed, 132 deletions(-) delete mode 100644 .claude/plans/developer-tools-tab.md diff --git a/.claude/plans/developer-tools-tab.md b/.claude/plans/developer-tools-tab.md deleted file mode 100644 index e960e183bb..0000000000 --- a/.claude/plans/developer-tools-tab.md +++ /dev/null @@ -1,132 +0,0 @@ -# Plan: "Developer tools" nav tab - -Status: **proposal, not applied.** The `mkdocs.yml` diff below is written to be copy-pasted and applied directly — by you, or by whoever reviews the resulting PR. I'm not applying it myself: `CLAUDE.md`'s hard rules say not to apply an information-architecture change on my own initiative, and that rule holds even under a direct instruction to proceed. Everything else in this plan (the two reference-doc edits) is already applied, since those aren't site changes. - -Classification decisions this plan depends on are recorded in [`.claude/reference/information-architecture.md`](../reference/information-architecture.md) — read that first if a "why" below is unclear. - -## What moves, what's new, what stays - -| Item | Action | File moves? | Redirect needed? | -|---|---|---|---| -| Codacy API (`codacy-api/` — using-the-API, tokens, examples, external Swagger links) | Relocate nav entry into the new tab | No | No | -| Codacy Cloud CLI (`codacy-cloud-cli/index.md`, includes the Codacy Skills pairing) | Relocate nav entry into the new tab | No | No | -| "Integrating Codacy with your IDE" (`getting-started/integrating-codacy-with-intellij-ides.md`, `-visual-studio-code.md`) | Relocate nav entry into the new tab, un-nest from "Getting started" | No | No | -| Codacy Guardrails (`codacy-guardrails/*`, 6 pages) | Relocate nav entry into the new tab; drop "(IDE Extension)" from the title | No | No | -| Codacy Analysis CLI, Codacy MCP Server | **Not extracted.** They stay inside the Guardrails page as-is — see the reference doc's "don't extract" rationale | — | — | -| Codacy Skills | **No page exists yet.** Stays as the install step inside Codacy Cloud CLI's page. A standalone page is separate `docs-write` work, not part of this move | — | — | -| Coverage Reporter | Excluded from this pass on your instruction | — | — | - -Every move in this table is a `nav:` entry relocation with the underlying files left in their current directories, which is why none of them need a `redirect_maps` entry: URLs derive from file path, not nav position, and no file path changes. - -## Naming decisions made along the way - -- Section titles for API and Cloud CLI are **left unchanged** — renaming them to bare "API" / "CLIs" was considered and dropped to keep the diff minimal; the current titles read fine one tab over. -- "Integrating Codacy with your IDE" is left unchanged for the same reason. If you'd rather it read "IDE extensions" once it's not nested under "Getting started" anymore, that's a one-word `sidebar_icons` key change too — flag it and I'll add it to the diff. -- "Codacy Guardrails (IDE Extension)" → **"Codacy Guardrails"** is the one title change in this plan, because the qualifier is factually wrong (see the reference doc) — this one isn't cosmetic. -- No new grouping node was added for "CLIs" or "MCP." Codacy Cloud CLI is the only thing that would live under a "CLIs" wrapper today, and Guardrails' CLI/MCP content stays inside Guardrails — so a wrapper category would hold either one item or nothing. Matches the "section holding one page" smell called out in `docs-review-structure`. - -## Cost / risk, beyond the table above - -- **New top-level tab:** no `sidebar_icons` entry needed for the tab itself — that config only governs items nested one level inside a tab (confirmed in `theme/partials/nav-item.html:20`), not the tab label. No `TemplateNotFound` risk. -- **Icon carry-over:** "Codacy API" and "Codacy Cloud CLI" keep their existing `sidebar_icons` entries untouched, since their titles don't change. Only the Guardrails rename needs its icon key updated (`shield-checkmark-outline` carries over to the new title). -- **No icon exists for "IDE extensions"-shaped content** in the closed ionicon set (`ls theme/assets/vendor/ionicons/svg/`). Leaving it unset is safe — no icon renders, no crash. Vendoring one is a separate `docs-review-theme` change, out of scope here. -- **Positioning trade-off, not a technical risk:** moving Guardrails out of the main Documentation tab demotes its visibility — it currently sits right under "Getting started" with a blog-post CTA. Check with whoever owns that placement before applying this piece specifically. - -## The `mkdocs.yml` diff - -Two edits: remove the four sections/entries from inside `Documentation`, and add a new `Developer tools` tab (placed between `Documentation` and `Release notes`) reusing them as-is except for the one Guardrails rename. - -**Remove from inside `- Documentation:`** (currently lines ~636–654 and ~717–730 in `mkdocs.yml`): - -```yaml - - Integrating Codacy with your IDE: - - getting-started/integrating-codacy-with-intellij-ides.md - - getting-started/integrating-codacy-with-visual-studio-code.md -``` -(this block moves out of `Getting started`, which keeps its other children) - -```yaml - - Codacy Guardrails (IDE Extension): - - codacy-guardrails/codacy-guardrails-getting-started.md - - codacy-guardrails/codacy-guardrails-how-to-use.md - - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md - - codacy-guardrails/codacy-guardrails-limitations.md - - codacy-guardrails/codacy-guardrails-troubleshooting.md - - codacy-guardrails/codacy-guardrails-faq.md - - Codacy Cloud CLI: - - codacy-cloud-cli/index.md -``` - -```yaml - - Codacy API: - - codacy-api/using-the-codacy-api.md - - codacy-api/api-tokens.md - - API v3 reference (recommended): https://api.codacy.com/api/api-docs - - API v2 reference: https://api.codacy.com/api-docs - - Examples: - - codacy-api/examples/adding-people-to-codacy-programmatically.md - - codacy-api/examples/adding-repositories-to-codacy-programmatically.md - - codacy-api/examples/creating-repository-api-tokens-programmatically.md - - codacy-api/examples/obtaining-code-quality-metrics-for-files.md - - codacy-api/examples/obtaining-current-issues-in-repositories.md - - codacy-api/examples/identifying-commits-without-coverage-data.md - - codacy-api/examples/uploading-dast-results.md - - codacy-api/examples/triggering-dast-scans.md -``` - -**Add as a new top-level tab**, sibling to `- Documentation:` and `- Release notes:`: - -```yaml - - Developer tools: - - Codacy API: - - codacy-api/using-the-codacy-api.md - - codacy-api/api-tokens.md - - API v3 reference (recommended): https://api.codacy.com/api/api-docs - - API v2 reference: https://api.codacy.com/api-docs - - Examples: - - codacy-api/examples/adding-people-to-codacy-programmatically.md - - codacy-api/examples/adding-repositories-to-codacy-programmatically.md - - codacy-api/examples/creating-repository-api-tokens-programmatically.md - - codacy-api/examples/obtaining-code-quality-metrics-for-files.md - - codacy-api/examples/obtaining-current-issues-in-repositories.md - - codacy-api/examples/identifying-commits-without-coverage-data.md - - codacy-api/examples/uploading-dast-results.md - - codacy-api/examples/triggering-dast-scans.md - - Codacy Cloud CLI: - - codacy-cloud-cli/index.md - - Integrating Codacy with your IDE: - - getting-started/integrating-codacy-with-intellij-ides.md - - getting-started/integrating-codacy-with-visual-studio-code.md - - Codacy Guardrails: - - codacy-guardrails/codacy-guardrails-getting-started.md - - codacy-guardrails/codacy-guardrails-how-to-use.md - - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md - - codacy-guardrails/codacy-guardrails-limitations.md - - codacy-guardrails/codacy-guardrails-troubleshooting.md - - codacy-guardrails/codacy-guardrails-faq.md -``` - -**`extra.sidebar_icons`** — one key rename, everything else untouched: - -```yaml - "Codacy Guardrails (IDE Extension)": "shield-checkmark-outline" -``` -becomes -```yaml - "Codacy Guardrails": "shield-checkmark-outline" -``` - -## Applying this - -1. Make the two nav edits and the one `sidebar_icons` key rename above in `mkdocs.yml`. -2. Run `mkdocs build --strict` (after `git submodule update --init --recursive` if the submodule content isn't checked out). This is the self-checking step: every one of the ~25 inbound relative links found during investigation (`grep -rn "codacy-api/\|codacy-cloud-cli\|codacy-guardrails/" docs/`) resolves by file path, unaffected by the nav move — if any of them were missed in this plan's accounting, the strict build fails loudly rather than shipping a broken link silently. -3. Spot-check the three in-repo links to `codacy-guardrails-getting-started.md#install-cli` (`client-side-tools.md`, `codacy-guardrails-troubleshooting.md`, `codacy-guardrails-faq.md`) still resolve — they should, since the file and its headings are untouched. -4. Preview the new tab locally and confirm: no icon renders for "Integrating Codacy with your IDE" (expected, no crash), Guardrails keeps its shield icon, API and Cloud CLI keep theirs. -5. Separately, before or alongside this: check with whoever owns Guardrails' marketing placement about the visibility trade-off noted above. - -## Explicitly out of scope for this pass - -- Extracting Codacy Analysis CLI or Codacy MCP Server into their own pages. -- Writing a first Codacy Skills page. -- Any change to Coverage Reporter's placement. -- Any theme change (external-link marker on the Swagger nav entries, a real "IDE" icon). From 3d1e171d16c1f866494600530e6f13075a9201eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 13 Aug 2026 11:06:50 +0100 Subject: [PATCH 6/7] switch VScode and IntelliJ --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 286840d3be..fdc93291e2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -761,11 +761,11 @@ nav: - codacy-api/examples/identifying-commits-without-coverage-data.md - codacy-api/examples/uploading-dast-results.md - codacy-api/examples/triggering-dast-scans.md - - Codacy Cloud CLI: + - Codacy CLIs: - codacy-cloud-cli/index.md - IDE integrations: - - getting-started/integrating-codacy-with-intellij-ides.md - getting-started/integrating-codacy-with-visual-studio-code.md + - getting-started/integrating-codacy-with-intellij-ides.md - Release notes: - release-notes/index.md - Cloud: From 1c13f027e02f4ae5faaa571d4f6e52857b01330f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 13 Aug 2026 11:17:12 +0100 Subject: [PATCH 7/7] fix icon --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index fdc93291e2..fc18932bd0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -76,7 +76,7 @@ extra: "Codacy dev tools": "settings-outline" "Getting started": "rocket-outline" "Codacy Guardrails": "shield-checkmark-outline" - "Codacy Cloud CLI": "terminal-outline" + "Codacy CLIs": "terminal-outline" "IDE integrations": "share-social-outline" "Codacy AI": "sparkles-outline" "Repositories on Codacy": "folder-open-outline"