Docs Infra + Info Architecture

[lbliii]

Documentation Restructure: Sphinx + MyST Markdown Migration

This PR establishes a complete documentation scaffold with improved information architecture and MyST Markdown compliance. The structural foundation is solid and production-ready, but content revision and verification required as all existing documentation was transposed using AI assistance.

⚠️ Important Content Notice

This PR prioritizes structure over content accuracy. While the documentation framework is robust and follows best practices, the content itself was migrated using AI-assisted tools (Cursor) and may contain:

• Factual distortions or inaccuracies
• Outdated API references or examples
• Missing edge cases or implementation details
• Incorrect parameter descriptions

---

🎯 What This PR Delivers

1. Modern Documentation Stack

• Sphinx + MyST Markdown: Full compliance with modern Sphinx documentation standards
• Enhanced Extensions: Custom extensions for advanced search, JSON output, (llm.txt coming soon!)
• Developer Ergonomics: make docs-live for local hot-reload development

2. Comprehensive Information Architecture

• About: Product overview, key features, core concepts, release notes
• Get Started: Installation guides and quickstart workflows
• Tutorials: Step-by-step learning paths
• Evaluation: Benchmark catalog, custom tasks, evaluation parameters, workflow guides
• Model Deployment: Launcher-orchestrated and BYOE deployment strategies
• Libraries: Complete API and CLI references for Core and Launcher
• Troubleshooting: Setup and runtime issue resolution
• References: API documentation and utility references

3. Structural Patterns & Best Practices

• Root index.md: Master toctree defining complete site navigation
• Directory Structure: Every directory begins with index.md for overview and routing
• Discovery UI: Grid-based card layouts for intuitive content discovery
• Content Reuse: _snippets/ directories demonstrating modular content patterns
• MyST Markdown Examples:
  • List tables ({list-table})
  • Interactive tabs ({tab-set}, {tab-item})
  • Collapsible sections ({dropdown})
  • Admonitions ({note}, {tip}, {warning}, {important})
  • Content inclusion ({include}, {literalinclude})
  • Substitutions for maintainable content

Comparison

Before

After

🚀 Getting Started for Reviewers

# Start live-reload server
make docs-live

---

📝 Review Priorities

1. Structure Review:

• Do the categories and subcategories work for your major user personas and their user journeys?
• Do they make sense for the mental model of your project?

2. Content Review (⚠️ Requires SME validation):
   • Swarm Technical accuracy of all content
     • P0: Get Started
     • P0: Run Evaluations
     • P0: Libraries
     • Troubleshooting can be deferred or removed until we're ready
   • Product stakeholders should own the Overview and Key Features documents
   • Identify what core concepts a new user would need to understand to be successful with evaluator and decide what changes to make for about/concepts/

Why This Approach?

Your content is still evolving rapidly at this moment; providing you with the required structure as a 1-time lift reduces bottlnecking and enables you to plug in your content a lot faster. Also, the distortion of the content even if staiblized is unavoidable due to transposing it from its current organizational state to something that follows a framework like https://diataxis.fr/

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.