docs: Add Airbyte branding and styling to pdoc documentation #804
Conversation
This commit adds custom CSS styling to the Python CDK API documentation to match the Airbyte brand identity: - Created custom theme.css to override pdoc's default theme with Airbyte colors - Created custom.css with comprehensive Airbyte branding (purple #615eff, Inter font) - Updated docs/generate.py to use the custom templates directory - Added documentation explaining the styling methodology and upstream sources The styling includes: - Airbyte purple color scheme for links and accents - Inter font family (Airbyte's brand font) - Styled tables with purple headers - Dark mode support - Comprehensive documentation about maintenance and updates This matches the styling already applied to PyAirbyte's documentation. Co-Authored-By: AJ Steers <[email protected]>
Original prompt from AJ Steers |
🤖 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. Testing This CDK VersionYou can test this version of the CDK using the following: # Run the CLI from this branch:
uvx 'git+https://github.com/airbytehq/airbyte-python-cdk.git@devin/1760996377-add-airbyte-branding-to-docs#egg=airbyte-python-cdk[dev]' --help
# Update a connector to use the CDK from this branch ref:
cd airbyte-integrations/connectors/source-example
poe use-cdk-branch devin/1760996377-add-airbyte-branding-to-docsHelpful ResourcesPR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
|
There was a problem hiding this comment.
Pull Request Overview
This PR adds Airbyte's brand identity to the Python CDK's pdoc-generated API documentation by creating custom CSS files that apply Airbyte's purple color scheme (#615eff), Inter font family, and styled components matching the main Airbyte documentation site.
Key changes:
- Created custom CSS files with Airbyte branding (purple colors, Inter font, styled tables with rounded corners)
- Added comprehensive inline documentation about maintenance and upstream sources
- Updated docs generation to use the new template directory
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/templates/theme.css | Overrides pdoc's default color variables with Airbyte purple theme |
| docs/templates/custom.css | Comprehensive custom styling including fonts, tables, dark mode, and interactive elements |
| docs/generate.py | Updates template directory path to use new docs/templates location |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughUpdates pdoc configuration to use a pathlib.Path for the template directory and adds two Airbyte-branded CSS files under Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Wdyt about adding a brief comment or README in Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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: 0
🧹 Nitpick comments (3)
docs/templates/theme.css (1)
1-22: Consider consolidating duplicated CSS variables?I notice that this file defines CSS variables in the
.pdocselector (lines 6-22) that are also defined incustom.css(lines 61-69). Specifically, these variables appear in both files:--link,--link-hover,--code,--accent,--text,--name, and--def.While the values are identical (so no conflict), this duplication could make maintenance harder. If Airbyte brand colors change, you'd need to update both files. Wdyt about consolidating these into a single source of truth? Perhaps keep theme.css as the token definitions and have custom.css reference them, or vice versa?
docs/templates/custom.css (2)
32-32: Consider optimizing font loading for performance?The Google Fonts import includes 6 font weights (200, 300, 400, 500, 600, 700), which means 6 separate font file downloads. This can impact page load performance, especially on slower connections.
Could you verify which weights are actually used in the documentation? Typically, 2-3 weights (e.g., 400, 600) are sufficient for most UIs. Also, consider adding
&display=swapto the font URL to prevent FOIT (Flash of Invisible Text) during loading.Example optimization:
-@import url("https://fonts.googleapis.com/css2?family=Inter:wght@200;300;400;500;600;700&display=swap"); +@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap");Wdyt?
252-260: Consider expanding responsive styling for mobile?The responsive adjustments for tablet/mobile are a good start. However, for very small screens (<480px), you might want to consider additional adjustments like:
- Adding horizontal scroll for tables (tables can be hard to read on small screens)
- Adjusting padding/spacing further
- Potentially stacking certain elements
Wdyt about enhancing mobile responsiveness in a follow-up? For now, the current implementation is acceptable.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/generate.py(1 hunks)docs/templates/custom.css(1 hunks)docs/templates/theme.css(1 hunks)
🔇 Additional comments (6)
docs/templates/custom.css (5)
72-102: Dark mode implementation looks solid!The dark mode support using
prefers-color-schemeis well-implemented. The color adjustments for dark mode look reasonable, and I appreciate that you're updating both:rootand.pdocvariables for consistency.
224-235: Excellent accessible focus styling!Great job providing custom focus styles with a visible focus ring (box-shadow) after removing the default outline. This maintains accessibility while matching the Airbyte brand. The 3px focus ring with the lightest purple shade is both visible and on-brand.
1-30: Outstanding documentation! 🎉The comprehensive header comments are exemplary. You've clearly documented:
- Methodology and design sources
- Upstream sync points for future updates
- pdoc integration details
- Key variables to maintain
This will make maintenance and updates much easier for future developers. Really appreciate the thorough approach here!
160-167: Verification confirms minimal !important usage—this is acceptable for third-party library overrides.The search confirms these are the only two
!importantdeclarations in your CSS files, both for navigation styling and clearly documented. Using!importantto override third-party library (pdoc) defaults is a standard pattern and perfectly reasonable here.That said, if you'd like to explore alternatives, increasing selector specificity (e.g.,
.pdoc nav a) might work and could be more maintainable long-term if you want to test it. Wdyt?
119-158: Table styling is accessible! ✓Great news—the contrast verification confirms your table headers pass WCAG AA standards with a ratio of 4.61:1 (exceeding the 4.5:1 requirement). The purple (#615eff) and white combination provides solid accessibility for users with visual impairments.
The entire table styling implementation looks solid: rounded corners, semantic markup, smooth hover effects, and now verified accessibility. No changes needed!
docs/generate.py (1)
68-68: Approved: pathlib.Path usage is correct and fully supported by pdoc.The change from string to
pathlib.Path("docs/templates")is solid. I verified thatpdoc.render.configure()acceptspathlib.Pathobjects for thetemplate_directoryparameter, and the template files are in place. This is more robust and idiomatic Python.
|
Devin, please address the copilot feedback. |
…irbyte Addresses Copilot feedback - the custom.css file is for the Python CDK documentation, not PyAirbyte documentation. Co-Authored-By: AJ Steers <[email protected]>
|
Both Copilot comments have been addressed:
Changes pushed in commit 9f10de5. |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/templates/custom.css (1)
119-260: Table, button, input, and responsive styles are well-executed.Tables have nice rounded corners and header styling with hover effects, buttons use brand colors with smooth transitions, and search inputs include accessible focus states. The responsive adjustments look good, though I notice only a single breakpoint at 768px. Is that intentional, or could smaller mobile viewports (e.g., 480px) benefit from additional adjustments? No blocker here—just curious about your approach, wdyt?
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/templates/custom.css(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Pytest (Fast)
- GitHub Check: Manifest Server Docker Image Build
- GitHub Check: SDM Docker Image Build
🔇 Additional comments (3)
docs/templates/custom.css (3)
1-30: Past copilot feedback successfully addressed.The file header comment correctly identifies this as "Python CDK Documentation - Custom Styling" and provides excellent guidance on methodology and maintenance (referencing upstream Airbyte sources and key variables to sync). Well done!
32-102: Color variables and dark mode support are well-structured.The CSS variables are cleanly organized with proper scoping to
:rootand.pdoc, and the dark mode inverts appropriately. One small note: per the PR objectives, dark mode support "not thoroughly tested"—would you like me to generate a verification script to help validate the dark mode color contrasts and readability?
160-167: Question about!importantusage for nav styling.Lines 162 and 166 use
!importantto override pdoc's nav default styles. While pragmatic, this can complicate future maintenance. Have you explored whether a higher-specificity selector (e.g.,.pdoc nav aor a more specific path) could achieve the same result without!important? If!importantis truly necessary here, a brief comment explaining why pdoc's defaults are hard to override would help future maintainers. Wdyt?
docs: Add Airbyte branding and styling to pdoc documentation
Summary
This PR duplicates the Airbyte branding work from PyAirbyte#832 to the Python CDK's API documentation. It applies Airbyte's visual identity (purple #615eff color scheme, Inter font family) to the pdoc-generated docs by:
docs/templates/directory with custom CSS files:theme.css: Overrides pdoc's default theme colors with Airbyte purplecustom.css: Comprehensive styling including fonts, tables, navigation, dark mode supportdocs/generate.pyto use the new templates directoryThe CSS files include documentation explaining the methodology and where to find upstream style updates when Airbyte's brand guidelines change.
Before and After
Before (current published docs):
After (with Airbyte branding):
Review & Testing Checklist for Human
poe docs-generatelocally to ensure docs still build successfully with the new template pathNotes
!importantflags in some places to override pdoc's default nav stylesSummary by CodeRabbit