Update qa-checks.md generation path to reflect Docusaurus multi-instance structure #69181
Conversation
…nce structure - Update integration test to reference new path: docs/community/contributing-to-airbyte/resources/qa-checks.md - Update template header comment with correct regeneration command - Update README.md with correct generation command - Update all versioned docs (1.6, 1.7, 1.8, 2.0) to use absolute path /community/contributing-to-airbyte/resources/qa-checks - Regenerate documentation at new location - Remove old file at docs/contributing-to-airbyte/resources/qa-checks.md Co-Authored-By: [email protected] <[email protected]>
Original prompt from [email protected] |
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. Helpful Resources
PR Slash CommandsAirbyte Maintainers (that's you!) can execute the following slash commands on your PR:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Replace docId references to 'contributing-to-airbyte/resources/qa-checks' with link items pointing to '/community/contributing-to-airbyte/resources/qa-checks' in all platform versioned sidebars (1.6, 1.7, 1.8, 2.0). This fixes the Docusaurus build failure caused by cross-instance doc references after the file moved from the platform plugin to the community plugin. Co-Authored-By: [email protected] <[email protected]>
...aurus/platform_versioned_docs/version-1.6/connector-development/testing-connectors/README.md
Outdated
Show resolved
Hide resolved
...aurus/platform_versioned_docs/version-1.7/connector-development/testing-connectors/README.md
Outdated
Show resolved
Hide resolved
...aurus/platform_versioned_docs/version-1.8/connector-development/testing-connectors/README.md
Outdated
Show resolved
Hide resolved
...aurus/platform_versioned_docs/version-2.0/connector-development/testing-connectors/README.md
Outdated
Show resolved
Hide resolved
Address PR feedback: 1. Fix generator templates to use absolute GitHub URLs instead of relative paths - Updated documentation_headers_check_description.md.j2 - Updated section_content_description.md.j2 - This fixes the broken link issue in the generated qa-checks.md 2. Update versioned docs to use site-root links (/community/...) instead of full URLs - Changed https://docs.airbyte.com/community/... to /community/... - Updated versions 1.6, 1.7, 1.8, and 2.0 3. Regenerate qa-checks.md with fixed templates - All 'standard template' links now use absolute GitHub URLs - Integration test passes successfully Co-Authored-By: [email protected] <[email protected]>
|
Good catch! I've fixed this by updating the generator templates to always use absolute GitHub URLs instead of relative paths. The issue was that the relative link Changes made:
The generated documentation now has working links to the standard template on GitHub. |
|
Agreed! I've updated all the versioned docs to use site-root links instead of full URLs. Changes made:
This follows the standard Docusaurus practice of using site-root links for internal documentation references. |
|
Deploy preview for airbyte-docs ready! ✅ Preview Built with commit af84a01. |
|
(aside) Commentary for reviewers: I noticed the way we generate public docs for connector QA tests didn't populate to the right place anymore (IE this doc: https://docs.airbyte.com/community/contributing-to-airbyte/resources/qa-checks). This file was out of date, while the docs generation script updated an orphaned file that didn't get built in the public docs. This broke after I migrated Docusaurus from a single instance to a multi-instance deployment ~6 months ago. I moved the location of the public docs, but didn't think to do the work that's been done here. I also noticed the generated public docs contained broken links because the Jinja templates used relative links that didn't work on the public web. The objective of this PR is to:
It updates the test, the checks themselves, and the output doc in Docusaurus, which should now have the latest version of the checks. What matters:
What doesn't matter:
|
ian-at-airbyte
added
area/documentation
What
Updates the
qa-checks.mdfile generation path to reflect the Docusaurus multi-instance structure migration. The file was previously generated atdocs/contributing-to-airbyte/resources/qa-checks.mdbut needed to be moved todocs/community/contributing-to-airbyte/resources/qa-checks.mdto align with the new multi-instance documentation structure where community docs live under thedocs/community/directory.Requested by: @ian-at-airbyte
Link to Devin run: https://app.devin.ai/sessions/1615d4a9393940ebb574182b7ba0bd29
How
Updated generation tooling:
docs/community/contributing-to-airbyte/resources/qa-checks.mdUpdated all versioned doc links (versions 1.6, 1.7, 1.8, 2.0):
./resources/qa-checks.mdto absolute path/community/contributing-to-airbyte/resources/qa-checkschange-cdk-connector.md,writing-connector-docs.md,testing-connectors/README.md, andconnector-breaking-changes.mdRegenerated documentation:
connectors-qa generate-documentation docs/community/contributing-to-airbyte/resources/qa-checks.mddocs/contributing-to-airbyte/resources/qa-checks.mdReview guide
Critical items to verify:
Page accessibility: Visit https://docs.airbyte.com/community/contributing-to-airbyte/resources/qa-checks after deployment to confirm the page is accessible at the intended URL
Link resolution in versioned docs: Check that the absolute path links
/community/contributing-to-airbyte/resources/qa-checksresolve correctly from the versioned platform docs (1.6, 1.7, 1.8, 2.0)Generated file content:
docs/community/contributing-to-airbyte/resources/qa-checks.md- Note that some content changed during regeneration (last section changed from "Testing" to "Version", and some links changed from absolute GitHub URLs to relative paths). Verify these changes are expected.Generation tooling:
airbyte-ci/connectors/connectors_qa/src/connectors_qa/templates/qa_checks.md.j2- Template header commentairbyte-ci/connectors/connectors_qa/tests/integration_tests/test_documentation.py- Integration test passes locallyairbyte-ci/connectors/connectors_qa/README.md- Documentation updatedSidebar navigation: Verify that sidebar navigation in
docusaurus/sidebar-community.jscorrectly references the doc and navigation works as expectedLess critical but worth checking:
cd docusaurus && pnpm clear && pnpm build) to catch any broken linksUser Impact
Users will now find the QA checks documentation at the correct location within the community documentation section, aligned with the multi-instance Docusaurus structure. All links to this documentation from versioned platform docs have been updated to point to the new location using absolute paths to avoid cross-instance navigation issues.
Potential negative impacts:
Can this PR be safely reverted and rolled back?
This change is purely documentation-related and can be safely reverted. The old file was deleted but can be restored from git history if needed. The integration test validates that the generation process works correctly with the new path.