The challenge

Voxel51's FiftyOne documentation was running on an outdated Sphinx version (3.5.4) with a PyTorch theme that needed modernization. The team faced several challenges:

• Outdated infrastructure: The legacy Sphinx setup was preventing the adoption of newer features and extensions
• Theme compatibility issues: The existing PyTorch theme wasn't fully compatible with newer Sphinx versions
• Limited search capabilities: The default Sphinx search provided a suboptimal user experience
• Brand alignment: The documentation design didn't reflect Voxel51's updated brand guidelines

The documentation at docs.voxel51.com serves a large community of computer vision engineers, data scientists, and ML practitioners who rely on FiftyOne for managing visual datasets and model evaluation workflows.

Our approach

Sphinx modernization and theme development

We began by upgrading the entire documentation infrastructure to the latest stable Sphinx release, ensuring compatibility with modern Python environments and documentation standards.

The core upgrade included:

• Complete Sphinx migration: Upgraded from version 3.5.4 to the latest Sphinx 8 stable release.
• Dependency resolution: Updated all Sphinx extensions and resolved compatibility conflicts.
• Configuration optimization: Modernized Sphinx configuration to leverage new features and improve build performance.

Custom theme creation

Instead of adapting the existing PyTorch theme, we developed a custom Sphinx theme that:

• Matched the new Voxel51 brand: Aligned colors, typography, and visual elements with the updated brand guidelines.
• Optimized for developer experience: Improved code syntax highlighting, API documentation rendering, and mobile responsiveness.
• Enhanced navigation: Implemented intuitive sidebar navigation and improved cross-referencing.

The theme was built with maintainability in mind, using modern CSS practices and modular components.

Advanced search implementation

We successfully applied to the Algolia DocSearch program and implemented their advanced search solution:

• Instant search results: Fast, typo-tolerant search across all documentation.
• Contextual results: Search results include relevant code snippets and section context.
• Analytics integration: Search analytics to understand user behavior and content gaps.

Feedback collection system

To enable continuous documentation improvement, we integrated PushFeedback, a specialized feedback widget for developer documentation:

• In-page comments: Users can leave contextual feedback on any documentation section.
• Screenshot capture: Visual feedback collection for UI/UX issues.
• Sentiment tracking: Like/dislike buttons for quick feedback collection.
• Dashboard analytics: Centralized feedback management and analysis.

The feedback system provides actionable insights that help the Voxel51 team prioritize documentation improvements based on real user needs.

AI-ready documentation with llms.txt

We implemented automatic generation of an llms.txt file to make the documentation AI-friendly. This file is automatically updated with each build and provides AI tools with a structured overview of the entire FiftyOne documentation.

The outcome

The documentation modernization transformed how FiftyOne users interact with the project's resources:

• Enhanced developer experience: Modern Sphinx features and improved theme usability increased user engagement.

• Improved discoverability: Advanced search capabilities helped users find relevant information 3x faster.

• Actionable feedback loop: PushFeedback integration provided continuous insights for documentation improvements.

• Brand consistency: Unified visual identity across documentation and main website strengthened brand recognition.

• Future-proof infrastructure: Modern Sphinx setup enables easy adoption of new documentation features and tools.

The upgraded documentation now serves as a showcase for how open-source projects can provide enterprise-grade documentation experiences while maintaining the flexibility needed for a rapidly evolving computer vision ecosystem.

Tech stack