docs: restructure /sync — uv-style sidebar, 7 new pages, voice pass#128
Conversation
- New pages: orchestration (schedule sync runs), side-by-side
pattern, migration walkthrough, schema mapping reference,
choosing an adapter, PeeringDB + Device42 adapter stubs.
- Moved: guides/ contents (installation, creation→create, run,
custom-certificates) to docs/docs/ root.
- Split: development.mdx → contributing.mdx (contributor docs)
+ RELEASING.md (maintainer release runbook) at repo root.
- Sidebar: uv-style structure — Get started · Guides · Adapters ·
Reference · Contributing.
- Titles: imperative form for task pages ("Create a sync project"),
noun form for reference.
- Voice pass on all new prose: drop "the team" third-person
paraphrasing, "without X" negation framing, and corporate-speak
verb+adverb constructions; lead with capability + use case,
not implementation type.
- 5 URL redirects via @docusaurus/plugin-client-redirects
(legacy /guides/* paths + /development → /contributing).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying infrahub-sync with
|
| Latest commit: |
092173b
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://765ac4d7.infrahub-sync.pages.dev |
| Branch Preview URL: | https://docs-sync-restructure.infrahub-sync.pages.dev |
|
Warning Review limit reached
More reviews will be available in 20 minutes and 14 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis PR restructures the Infrahub Sync documentation from a legacy /guides/* path structure to top-level documentation pages. New foundational guides explain how to create sync projects, run syncs, configure custom certificates, and contribute code. A comprehensive schema mapping reference consolidates field mapping syntax and examples. Production and migration guides cover orchestration, gradual NetBox/Nautobot migration, and side-by-side adoption patterns. New adapter documentation for Device42 and PeeringDB is added alongside a selecting-an-adapter guide. Navigation is wired through Docusaurus redirects, sidebar restructuring, and internal link updates. Legacy guide files are removed, RELEASING.md is rewritten as a release runbook, and supporting changes include contributor documentation and spelling exceptions. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (4)
docs/docs/adapters/peeringdb.mdx (2)
5-7: ⚡ Quick winRemove unused imports.
The stub imports
ReferenceLink,Tabs, andTabItembut doesn't use them. Clean up these imports until the page is fleshed out.🧹 Proposed cleanup
-import ReferenceLink from "../../src/components/Card"; -import Tabs from '`@theme/Tabs`'; -import TabItem from '`@theme/TabItem`'; -🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/peeringdb.mdx` around lines 5 - 7, Remove the unused imports ReferenceLink, Tabs, and TabItem from the top of the peeringdb.mdx stub by deleting their import statements (the lines that import ReferenceLink from "../../src/components/Card" and Tabs/TabItem from '`@theme/`*'); keep the file otherwise unchanged and re-add these imports only when the components are actually used.
9-9: 💤 Low valueVale sentence-case warning on proper noun.
The pipeline flags "What is PeeringDB?" as violating sentence case, but "PeeringDB" is a proper noun with specific capitalization. If Vale continues to flag this, consider adding a vale-off comment or updating the Vale rule to handle product names.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/peeringdb.mdx` at line 9, The header "## What is PeeringDB?" is being flagged by Vale for sentence-case but "PeeringDB" is a proper noun; either suppress the lint for this occurrence by wrapping or annotating the header with a Vale disable comment (e.g., add a Vale inline disable/enable around the "## What is PeeringDB?" header) or add "PeeringDB" to the Vale allowed words/wordlist/style configuration so the rule accepts its capitalization; update the docs line containing the header or the Vale config accordingly.docs/docs/adapters/device42.mdx (2)
5-7: ⚡ Quick winRemove unused imports.
The stub imports
ReferenceLink,Tabs, andTabItembut doesn't use them. Clean up these imports until the page is fleshed out.🧹 Proposed cleanup
-import ReferenceLink from "../../src/components/Card"; -import Tabs from '`@theme/Tabs`'; -import TabItem from '`@theme/TabItem`'; -🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/device42.mdx` around lines 5 - 7, The file imports unused symbols ReferenceLink, Tabs, and TabItem; remove those import statements (the import lines that reference ReferenceLink, Tabs, and TabItem) so there are no unused imports remaining until the page uses those components; if you plan to re-add later, keep a single TODO comment instead of importing unused symbols.
9-9: 💤 Low valueVale sentence-case warning on proper noun.
The pipeline flags "What is Device42?" as violating sentence case, but "Device42" is a proper noun with specific capitalization. If Vale continues to flag this, consider adding a vale-off comment or updating the Vale rule to handle product names.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/device42.mdx` at line 9, The Vale linter is flagging the heading "What is Device42?" as a sentence-case violation even though "Device42" is a proper noun; fix by either disabling Vale for that heading or adding a Vale exception: add an inline Vale disable comment around the heading (e.g., <!-- vale off --> before the "What is Device42?" heading and <!-- vale on --> after the block) or add a rule/term exception in your Vale config to whitelist "Device42" so the header is no longer flagged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/docs/contributing.mdx`:
- Line 57: Update the heading "Validate the CLI" to sentence case by
capitalizing only the first word and leaving the acronym as-is (e.g., "Validate
the CLI"); if Vale still flags Infrahub.sentence-case for that heading, add a
Vale directive to disable that rule for this line (disable
Infrahub.sentence-case for the heading) so the acronym "CLI" is accepted; target
the heading text "Validate the CLI" when making the change.
In `@docs/docs/migrating-from-netbox-or-nautobot.mdx`:
- Line 100: Update the heading "## Phase 5 — Migrate workflows" to sentence-case
by lowercasing the subtitle after the em dash; find the heading string "## Phase
5 — Migrate workflows" and change it to "## Phase 5 — migrate workflows" so it
passes the Infrahub.sentence-case Vale check.
- Line 120: Update the MDX heading "## Differences between migrating from NetBox
versus Nautobot" to sentence-case to satisfy Vale; change it to something like
"## Differences between migrating from NetBox and Nautobot" (keep proper nouns
like NetBox and Nautobot capitalized) so the heading matches the
Infrahub.sentence-case rule.
In `@docs/docs/readme.mdx`:
- Line 5: The Vale spellcheck is flagging “ServiceNow-style CMDBs” because the
token CMDBs is not in the Vale exceptions file; open spelling-exceptions.txt
(the Vale spelling exceptions list) and add a new entry "CMDBs" (exact casing)
on its own line so Vale will accept the phrase in docs/docs/readme.mdx; commit
the change to unblock the build.
In `@docs/docs/using-netbox-or-nautobot-with-infrahub.mdx`:
- Line 59: The MDX sentence contains the flagged word "queryable"; fix by either
adding "queryable" to the Vale exceptions (spelling-exceptions.txt) or by
rephrasing the sentence to avoid the term (e.g., change "the same data is
queryable via Infrahub's graph traversal capabilities" to "the same data can be
queried via Infrahub's graph traversal capabilities"); update the docs line
containing "queryable via Infrahub's graph traversal capabilities" accordingly
and run Vale/markdownlint to confirm the validation passes.
---
Nitpick comments:
In `@docs/docs/adapters/device42.mdx`:
- Around line 5-7: The file imports unused symbols ReferenceLink, Tabs, and
TabItem; remove those import statements (the import lines that reference
ReferenceLink, Tabs, and TabItem) so there are no unused imports remaining until
the page uses those components; if you plan to re-add later, keep a single TODO
comment instead of importing unused symbols.
- Line 9: The Vale linter is flagging the heading "What is Device42?" as a
sentence-case violation even though "Device42" is a proper noun; fix by either
disabling Vale for that heading or adding a Vale exception: add an inline Vale
disable comment around the heading (e.g., <!-- vale off --> before the "What is
Device42?" heading and <!-- vale on --> after the block) or add a rule/term
exception in your Vale config to whitelist "Device42" so the header is no longer
flagged.
In `@docs/docs/adapters/peeringdb.mdx`:
- Around line 5-7: Remove the unused imports ReferenceLink, Tabs, and TabItem
from the top of the peeringdb.mdx stub by deleting their import statements (the
lines that import ReferenceLink from "../../src/components/Card" and
Tabs/TabItem from '`@theme/`*'); keep the file otherwise unchanged and re-add
these imports only when the components are actually used.
- Line 9: The header "## What is PeeringDB?" is being flagged by Vale for
sentence-case but "PeeringDB" is a proper noun; either suppress the lint for
this occurrence by wrapping or annotating the header with a Vale disable comment
(e.g., add a Vale inline disable/enable around the "## What is PeeringDB?"
header) or add "PeeringDB" to the Vale allowed words/wordlist/style
configuration so the rule accepts its capitalization; update the docs line
containing the header or the Vale config accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 23aaf314-0de6-454b-b476-172e1bbfb438
⛔ Files ignored due to path filters (1)
docs/package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (24)
.vale/styles/spelling-exceptions.txtREADME.mdRELEASING.mddocs/docs/adapters/choosing-an-adapter.mdxdocs/docs/adapters/device42.mdxdocs/docs/adapters/nautobot.mdxdocs/docs/adapters/netbox.mdxdocs/docs/adapters/peeringdb.mdxdocs/docs/contributing.mdxdocs/docs/creating-a-sync-project.mdxdocs/docs/custom-certificates.mdxdocs/docs/guides/creation.mdxdocs/docs/guides/custom-certificates.mdxdocs/docs/installation.mdxdocs/docs/migrating-from-netbox-or-nautobot.mdxdocs/docs/orchestration.mdxdocs/docs/readme.mdxdocs/docs/reference/config.mdxdocs/docs/reference/schema-mapping.mdxdocs/docs/running-a-sync.mdxdocs/docs/using-netbox-or-nautobot-with-infrahub.mdxdocs/docusaurus.config.tsdocs/package.jsondocs/sidebars.ts
💤 Files with no reviewable changes (2)
- docs/docs/guides/creation.mdx
- docs/docs/guides/custom-certificates.mdx
| uv run mypy infrahub_sync/ --ignore-missing-imports | ||
| ``` | ||
|
|
||
| ### Validate the CLI |
There was a problem hiding this comment.
Resolve Vale sentence-case warning.
The pipeline reports a Vale warning that contradicts the PR's claim of "0 errors." The heading may need adjustment to satisfy the Infrahub.sentence-case rule, though the current capitalization of "CLI" as an acronym appears correct.
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[warning] 57-57: Vale (Infrahub.sentence-case) warning: 'Validate the CLI' should use sentence case.
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[warning] 57-57: Vale (Infrahub.sentence-case) warning: 'Validate the CLI' should use Infrahub.sentence-case sentence case.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/contributing.mdx` at line 57, Update the heading "Validate the CLI"
to sentence case by capitalizing only the first word and leaving the acronym
as-is (e.g., "Validate the CLI"); if Vale still flags Infrahub.sentence-case for
that heading, add a Vale directive to disable that rule for this line (disable
Infrahub.sentence-case for the heading) so the acronym "CLI" is accepted; target
the heading text "Validate the CLI" when making the change.
|
|
||
| During side-by-side operation, the same model may be edited in both tools. Decide upfront which tool is authoritative for each model and document the decision in the project configuration. If both tools allow edits to the same model, conflicts will eventually occur — and Infrahub Sync's default behavior is for the source system to win. | ||
|
|
||
| ## Phase 5 — Migrate workflows |
There was a problem hiding this comment.
Fix heading to pass Vale sentence-case check.
The pipeline flags this heading as violating the Infrahub.sentence-case rule. Based on the Vale error, this heading should be adjusted to pass the sentence-case validation.
As per coding guidelines, Markdown and MDX files in docs must pass markdownlint-cli2 checks, and the pipeline shows this is currently failing Vale validation.
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[warning] 100-100: Vale (Infrahub.sentence-case) warning: 'Phase 5 — Migrate workflows' should use sentence case.
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[warning] 100-100: Vale (Infrahub.sentence-case) warning: 'Phase 5 — Migrate workflows' should use sentence case.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/migrating-from-netbox-or-nautobot.mdx` at line 100, Update the
heading "## Phase 5 — Migrate workflows" to sentence-case by lowercasing the
subtitle after the em dash; find the heading string "## Phase 5 — Migrate
workflows" and change it to "## Phase 5 — migrate workflows" so it passes the
Infrahub.sentence-case Vale check.
|
|
||
| Many teams reach a stable side-by-side state and stay there indefinitely. See [Use NetBox or Nautobot with Infrahub](./using-netbox-or-nautobot-with-infrahub.mdx). | ||
|
|
||
| ## Differences between migrating from NetBox versus Nautobot |
There was a problem hiding this comment.
Fix heading to pass Vale sentence-case check.
The pipeline flags this heading as violating the Infrahub.sentence-case rule. Based on the Vale error, this heading should be adjusted to pass the sentence-case validation.
As per coding guidelines, Markdown and MDX files in docs must pass markdownlint-cli2 checks, and the pipeline shows this is currently failing Vale validation.
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[warning] 120-120: Vale (Infrahub.sentence-case) warning: 'Differences between migrating from NetBox versus Nautobot' should use sentence case.
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[warning] 120-120: Vale (Infrahub.sentence-case) warning: 'Differences between migrating from NetBox versus Nautobot' should use sentence case.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/migrating-from-netbox-or-nautobot.mdx` at line 120, Update the MDX
heading "## Differences between migrating from NetBox versus Nautobot" to
sentence-case to satisfy Vale; change it to something like "## Differences
between migrating from NetBox and Nautobot" (keep proper nouns like NetBox and
Nautobot capitalized) so the heading matches the Infrahub.sentence-case rule.
Resolve two docs conflicts in favour of the restructured branch: - docs/docs/readme.mdx: keep the restructured overview (flat paths, "How it works" / "Who it's for" / "What's included" sections) over main's older link-list readme. - docs/docs/running-a-sync.mdx: keep main's v2.0.0 body (cache/incremental extraction, --parallel tiering, rowcount guardrail, cached-plan apply) and resolve only the intro :::info note to the restructured link (./creating-a-sync-project.mdx). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Vale's Infrahub.spelling rule flagged two errors that failed the validate-documentation-style CI job: - readme.mdx:5 — 'CMDBs' (ServiceNow-style CMDBs) in the restructured intro - using-netbox-or-nautobot-with-infrahub.mdx:59 — 'queryable' Both are legitimate technical terms; add them to the spelling exception list. Vale now reports 0 errors (remaining sentence-case warnings do not fail the build; exit 0 confirmed locally). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2 participants
Summary by CodeRabbit
Documentation
Chores
Restructure the
/sync/docs section. Single production PR — goes live todocs.infrahub.app/syncon merge.docs/docs/guides/to rootdevelopment.mdx→contributing.mdx+RELEASING.md(maintainer runbook moves to repo root)@docusaurus/plugin-client-redirectsFull project plan with rationale: Confluence — Overview project plan.
Final sidebar
What needs reviewer attention
Sorted by how much new content needs verification.
Net-new prose — read end-to-end
docs/docs/orchestration.mdxdocs/docs/using-netbox-or-nautobot-with-infrahub.mdxdocs/docs/migrating-from-netbox-or-nautobot.mdxSKIP_UNMATCHED_DSTbehavior description, and the differences-between-NetBox-and-Nautobot section.docs/docs/reference/schema-mapping.mdxinfrahub_sync/__init__.py:114-130(the prior table inconfig.mdxwas wrong). NetBox + Nautobot worked examples are illustrative — verify field names.docs/docs/adapters/choosing-an-adapter.mdxRELEASING.md(repo root)development.mdx; no content changes, only location. Verify it still reads as a coherent runbook on its own.Stub pages — minimal content, just confirm framing
docs/docs/adapters/peeringdb.mdx— "Under Construction" stub matching the LibreNMS/Observium pattern.docs/docs/adapters/device42.mdx— same.Rewrites — compare against original
creating-a-sync-project.mdxguides/creation.mdx, but reshaped: dropped "this guide will walk you through" opener; "Step 1/2/3/4" headings → action-named (Define source & destination / Set the sync order / Map the schema fields / Tune sync behavior). Nautobot → Infrahub example preserved.custom-certificates.mdxguides/custom-certificates.mdx, but reshaped: dropped "this guide will walk you through" opener; collapsed 4 single-command steps into 2 action-named sections. Adds a note that paths shown are Debian/Ubuntu-specific.contributing.mdxdevelopment.mdx. Content above the "Publishing a release" section preserved verbatim. The 180-line Release Runbook moved to/RELEASING.md. Opens with a one-line pointer to RELEASING.md.Targeted edits — small surface area
docs/docs/reference/config.mdxschema-mapping.mdx), replaced with brief mention + pointer. Structural tables (Mapping models / fields / filters / transforms) unchanged.docs/docs/adapters/netbox.mdxdocs/docs/adapters/nautobot.mdxdocs/docs/readme.mdx(overview)README.md(repo root)/sync/URLs and new imperative titles ("Create a sync project" etc.)..vale/styles/spelling-exceptions.txtPage renames
All task-page titles converted from gerund to imperative form (matches the imperative voice in the body prose, and matches Stripe / FastAPI / Pulumi convention for how-to pages):
Reference page titles kept as noun-phrase (they describe a thing, not an action).
URL redirects
Configured via
@docusaurus/plugin-client-redirectsindocs/docusaurus.config.ts(pinned to3.10.0to match Docusaurus core):/sync/guides/installation/sync/installation/sync/guides/creation/sync/creating-a-sync-project/sync/guides/run/sync/running-a-sync/sync/guides/custom-certificates/sync/custom-certificates/sync/development/sync/contributingVerification
cd docs && npm run buildsucceedsnpx markdownlint-cli2— clean across 30 files (0 errors)vale docs/docs/— 0 errors in new/touched content. Remaining errors are all in pre-existingmedia/infrahub_sync_process.excalidraw.svg(embedded font tokens — out of scope)build/<old-path>/http://localhost:3010/Out of scope (deferred)
Tracked as Open Issues on the Confluence project plan:
Test plan