Blue Robotics is a leading provider of marine robotics technology, offering open-source hardware and software solutions for underwater exploration and research. They manage documentation for over 10 open-source projects using various Markdown-based technologies.

We helped Blue Robotics migrate to a unified documentation system using Sphinx, creating a custom theme that supports multiple languages and versions while maintaining a consistent user experience across all projects.

The challenge

As Blue Robotics grew its product line, its documentation became increasingly fragmented. Different projects relied on different documentation tools, creating an inconsistent experience for both users and contributors.

To address this challenge, Blue Robotics needed a centralized, scalable documentation system—one that could streamline content management, deliver a cohesive user experience, and support their continued growth.

Our approach

Custom Sphinx theme development

We developed a custom Sphinx theme with Material design aesthetics that included:

• Branding integration with Blue Robotics' visual identity
• Multi-language support for C++, Python, and Lua
• Dark mode toggle and responsive design
• Customizable navigation and footer sections
• Integrated search functionality
• SEO optimization and social sharing features

Multi-version documentation system

We implemented a custom CI/CD pipeline for version management that:

• Automatically builds and publishes documentation for multiple versions
• Provides a version selector dropdown
• Maintains version-specific URLs and content
• Integrates with GitHub Actions for automated builds
• Supports self-hosting on GitHub Pages

Pilot project implementation

We started with a pilot project to validate the new system:

• Migrated existing Markdown content to Sphinx
• Autogenerated Python reference documenation from source code
• Configured the custom theme and multi-version support
• Set up automated workflows for documentation updates
• Created detailed installation guides for future projects

The outcome

The new documentation system transformed how Blue Robotics manages their technical content:

• Unified experience: Consistent look and feel across all projects
• Automated workflows: Reduced manual maintenance with CI/CD
• Developer-friendly: Support for automatic documentation generation
• Scalable solution: Easy to extend to new projects and versions

The result is a robust documentation platform that grows with Blue Robotics' needs while maintaining a high-quality user experience.

Tech stack