docs: rewrite sync overview page#125
Merged
Merged
Conversation
The previous overview at docs/docs/readme.mdx was an index of links to guides, references, and adapters. The new version is a narrative overview that introduces what Infrahub Sync is, the three core concepts (sync project, adapter, schema mapping), how the diff/sync workflow operates, who the tool is for, what's included, and common questions teams ask before adopting. All existing links from the old index are preserved across the new sections (How it works, Get started, and Additional resources). Content sourced from the recent OpsMill messaging brief for Infrahub Sync; facts verified against the repo (adapters, CLI commands, diffsync_flags, filter operations, Python version range). Also adds spelling exceptions for terms used in the new content: cron, cutover, declaratively, diffsync, Prefect, Slurp'it, Typer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
yjouffrault
added
type/documentation
Deploying infrahub-sync with
|
| Latest commit: |
1641e1a
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://a7100f68.infrahub-sync.pages.dev |
| Branch Preview URL: | https://docs-update-sync-overview.infrahub-sync.pages.dev |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughThis PR updates documentation and configuration: it expands the Vale spelling-exceptions list with new product terms and replaces the brief README with a comprehensive Infrahub Sync product README covering purpose, core concepts, CLI commands (diff, sync, generate, list), adapter library and directionality, installation/get-started steps, a common-questions FAQ, and consolidated resource links. 🚥 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 |
Addresses audit finding #2: the Concepts callout introduced `generate` as one of three CLI commands operating on a sync project, but the subsections that followed only covered Define / Preview / Execute. A reader saw `generate` named once and then never explained on the page. Adds a short subsection between "Define a sync project" and "Preview with diff" describing what `generate` does and when to re-run it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…urp'it apostrophe Three small audit follow-ups against the new overview page: - Adapter description: replace "pagination" with "request handling". The blanket claim that every adapter handles pagination is optimistic for the Generic REST API adapter, which has no explicit pagination logic; SDK-based adapters (NetBox, Nautobot, IP Fabric) handle it internally via their SDKs. "Request handling" covers the general responsibility without overclaiming. - Drop "renames" from the schema-mapping bullet. The schema model has no "rename" concept distinct from a direct mapping; the word read as a separate feature alongside identifiers/references/static values but isn't one. - Normalize Slurp'it to the typographic apostrophe (Slurp'it), matching the convention used in docs/docs/adapters/slurpit.mdx. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The line "Three key concepts in Infrahub Sync:" did not add information over the section heading. The three bullets stand on their own; the closing "Three CLI commands operate on a sync project: …" line still provides the connection to the subsections that follow. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
BeArchiTek
approved these changes
May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
Rewrites the Infrahub Sync docs overview page at
docs/docs/readme.mdxfrom an index of links into a narrative overview, grounded in the recent OpsMill messaging brief for Infrahub Sync.The previous version was four lists (Guides, Reference, Adapters, Contributing) under a single intro paragraph. The new version introduces what Infrahub Sync is, the three core concepts a reader needs to navigate the rest of the documentation, how the
generate/diff/syncworkflow operates, who the tool is for, what's included, and a short Common questions section. Every link from the previous index lands somewhere in the new structure — How it works, Get started, or Additional resources.Structure
Verified facts
All product claims in the new page were verified against the repo:
docs/docs/adapters/*.mdx)list,diff,generate,sync)diffsync_flags,INFRAHUB_SYNC_ADAPTER_PATHSVale + markdownlint
Both pass cleanly. Spelling exceptions added for terms used in the new content:
cron,cutover,declaratively,diffsync,Prefect,Slurp'it,TyperVerification
vale docs/docs/readme.mdx→ 0 errors, 0 warningsnpx markdownlint-cli2 docs/docs/readme.mdx→ 0 errorscd docs && npm run build→ succeeds, no broken-link warnings on the new page🤖 Generated with Claude Code