docs: Add Airbyte branding and styling to pdoc documentation #832
Conversation
- Create custom CSS template with Airbyte color scheme and design elements - Update pdoc configuration to use custom template directory - Add Vercel configuration for deploying docs to py.airbyte.docs - Apply Inter font family and Airbyte primary colors (#615eff) - Style tables, links, code blocks, and other elements with Airbyte theme - Support both light and dark mode color schemes Co-Authored-By: AJ Steers <aj@airbyte.io>
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 PyAirbyte VersionYou can test this version of PyAirbyte using the following: # Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1760992087-add-airbyte-branding-to-docs' pyairbyte --help
# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1760992087-add-airbyte-branding-to-docs'Helpful ResourcesPR Slash CommandsAirbyte Maintainers can execute the following slash commands on your PR:
Community SupportQuestions? Join the #pyairbyte channel in our Slack workspace. |
- Override pdoc's --link and --link-hover variables directly - Add comprehensive documentation about methodology and upstream sources - Document how to update styles when Airbyte brand changes - Reference main Airbyte docs CSS as source of truth - Clean up redundant CSS rules that weren't working Co-Authored-By: AJ Steers <aj@airbyte.io>
📝 WalkthroughWalkthroughAdds Airbyte-branded pdoc templates and CSS, introduces Vercel deployment configuration, and changes a pdoc template path argument to a pathlib.Path in docs/generate.py; no public API or function signatures were modified. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Would you like me to add a short note to the README documenting the Vercel buildCommand and outputDirectory to help future contributors, wdyt? 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: 1
🧹 Nitpick comments (3)
vercel.json (1)
2-2: Consider optimizing the build command to skip dev dependencies, wdyt?The build installs all dependencies including dev dependencies. If the documentation generation doesn't require dev dependencies, you could speed up builds by using
poetry install --only mainorpoetry install --no-dev.Apply this diff if dev dependencies aren't needed:
- "buildCommand": "poetry install && poetry run poe docs-generate", + "buildCommand": "poetry install --only main && poetry run poe docs-generate",docs/templates/custom.css (2)
6-6: Heads up: External font dependency on Google Fonts, wdyt about self-hosting?The CSS imports Inter font from Google's CDN, which adds an external dependency and privacy implications (Google tracks font requests). For a privacy-focused or offline-capable documentation site, consider self-hosting the fonts or using system fonts as a fallback.
If you prefer to self-host, you could download the font files and reference them locally:
@font-face { font-family: 'Inter'; src: url('/fonts/inter-var.woff2') format('woff2'); font-weight: 200 700; font-display: swap; }
40-65: The--color-whitevariable becomes dark gray in dark mode - intentional for theming?On line 58,
--color-whiteis set tohsl(0, 0%, 16%)(dark gray) in dark mode. While this might be intentional for inverting backgrounds (e.g., table headers, buttons), the variable name--color-whiteis semantically misleading when it holds a dark value.Consider renaming it to something like
--color-surfaceor--color-bg-primaryto better reflect its purpose as a themeable surface color rather than a literal white. Wdyt?
📜 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)vercel.json(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). (6)
- GitHub Check: Pytest (All, Python 3.11, Windows)
- GitHub Check: Pytest (All, Python 3.11, Ubuntu)
- GitHub Check: Pytest (All, Python 3.10, Windows)
- GitHub Check: Pytest (All, Python 3.10, Ubuntu)
- GitHub Check: Pytest (No Creds)
- GitHub Check: Pytest (Fast)
🔇 Additional comments (3)
docs/templates/custom.css (2)
177-190: Button text color may have the same dark mode contrast issue, wdyt?Similar to the table headers, buttons use
--airbyte-primaryas background (line 178) and--color-whiteas text color (line 179). In dark mode, this results in light purple background with dark gray text, which might have contrast issues.Consider using a color that guarantees sufficient contrast, or test the actual rendered output in dark mode as mentioned in the PR testing notes.
112-117: Verify color contrast in table headers for dark mode accessibility, wdyt?Table headers use
--airbyte-primaryas the background (line 113) and--color-whiteas the text color (line 114). In dark mode,--airbyte-primaryis#7976ffand--color-whitebecomeshsl(0, 0%, 16%)(dark gray). This combination might not meet WCAG contrast requirements.Run the following script to check the contrast ratio:
docs/generate.py (1)
27-35: LGTM! Good use ofpathlib.Pathfor consistency.Converting
template_directoryto usepathlib.Pathaligns with the other path handling in this file (lines 24 and 38) and is more explicit than using a string. This change properly configures pdoc to use the new custom.css template from thedocs/templatesdirectory.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/templates/custom.css (1)
243-252: Mobile responsive design included.Good to see a media query for smaller screens. Consider whether these breakpoints align with pdoc's expected responsive behavior, and whether additional breakpoints (e.g., 1024px for tablets) would benefit the documentation layout. 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). (5)
- GitHub Check: Pytest (All, Python 3.10, Ubuntu)
- GitHub Check: Pytest (Fast)
- GitHub Check: Pytest (All, Python 3.11, Windows)
- GitHub Check: Pytest (All, Python 3.11, Ubuntu)
- GitHub Check: Pytest (No Creds)
🔇 Additional comments (5)
docs/templates/custom.css (5)
1-30: Excellent upstream documentation.The header comments clearly reference the source (Airbyte docs site, Docusaurus config) and outline the methodology for keeping styles in sync. This is helpful for future maintenance.
106-109: Verify pdoc output uses these class names.The CSS targets
.pdoc-code(line 200) and earlier references.badge(line 162), but I'm not certain these classes exist in pdoc's generated HTML. Wdyt—should these be verified against actual pdoc output to avoid dead code? If pdoc doesn't generate these classes, consider removing them or testing the generated docs to confirm.Also applies to: 199-203
210-213: Subtle shadow improves visual hierarchy.The
box-shadowonmain(0 2px 8px with low opacity) is a nice touch for depth without overwhelming the content.
111-150: Table styling is thorough and accessible.Nice touch with the hover transition, rounded corners, and clear header styling. One thought: the hover background color change helps with row scanning on larger tables. Just ensure the contrast between
var(--color-grey-40)and text meets WCAG standards, especially in dark mode where greys are reversed.
34-94: Verify dark mode color contrast and rendering.The light and dark mode color palettes look comprehensive, but have you verified WCAG AA contrast ratios for text and interactive elements? For example, the primary purple (#615eff) on white or the lighter variants in dark mode. Also, the PR notes mention dark mode rendering wasn't fully tested—wdyt about verifying this with a browser dev tools inspection once docs are generated locally?
You can test locally with:
To check contrast ratios, reference WCAG guidelines or use tools like WebAIM Contrast Checker.
- Created custom theme.css to override pdoc's default color scheme - Fixed nav link CSS to use correct --link variable with !important - All links (nav and main content) now display in Airbyte purple (#615eff) - Added documentation about CSS variable usage and maintenance Co-Authored-By: AJ Steers <aj@airbyte.io>
GitHub Pages is already configured and working for documentation hosting, so the Vercel configuration is not needed. Co-Authored-By: AJ Steers <aj@airbyte.io>
docs: Add Airbyte branding and styling to pdoc documentation
Summary
This PR adds Airbyte branding and styling to the PyAirbyte pdoc-generated documentation by creating a custom CSS template that incorporates Airbyte's design system. It also adds Vercel configuration for deploying the docs to a subdomain (py.airbyte.docs or similar).
Changes:
docs/templates/custom.csswith Airbyte color scheme (#615eff purple), Inter font family, and styled components (tables, links, code blocks, etc.)docs/generate.pyto use the newdocs/templatesdirectoryvercel.jsonconfiguration for Vercel deploymentReview & Testing Checklist for Human
poetry run poe docs-generate) and verify styling looks good across multiple documentation pages (not just index.html)Test Plan
Notes
airbyte/docusaurus/src/css/custom.css)Summary by CodeRabbit
New Features
Chores
Important
Auto-merge enabled.
This PR is set to merge automatically when all requirements are met.