Mintlify compatibility

.github/workflows/docs.yaml

@@ -46,11 +46,11 @@ jobs:
           python -m pip install .[docs]
       - name: Build Sphinx site
         run: |
-          sphinx-build -b html docs/ docs/_build/html
+          sphinx-build -b html docs/sphinx docs/sphinx/_build/html
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/_build/html
+          path: docs/sphinx/_build/html
 
   deploy:
     environment:

.gitignore

@@ -73,7 +73,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/*/_build/
 
 # PyBuilder
 .pybuilder/

CONTRIBUTING.md

@@ -82,26 +82,30 @@ uv pip install .[docs]
 Using the Makefile generated by Sphinx:
 
 ```bash
-make -C docs html
+make -C docs/sphinx html
 ```
 
 Or directly with sphinx-build:
 
 ```bash
-sphinx-build -b html docs/ docs/_build/html
+sphinx-build -b html docs/sphinx docs/sphinx/_build/html
 ```
 
 Open the result in your browser:
 
 ```bash
 # Linux
-xdg-open docs/_build/html/index.html
+xdg-open docs/sphinx/_build/html/index.html
+
+# Or serve locally
+make -C docs/sphinx serve
+# Opens at http://localhost:8000/
 ```
 
 Clean build artifacts:
 
 ```bash
-make -C docs clean
+make -C docs/sphinx clean
 ```
 
 ### Publishing (CI)

REUSE.toml

@@ -45,3 +45,32 @@ path = "**/*.ico"
 SPDX-FileCopyrightText = "2025 InOrbit, Inc."
 SPDX-License-Identifier = "MIT"
 SPDX-FileComment = "ICO assets"
+
+# Documentation content files (portable between Sphinx and Mintlify)
+# These use YAML frontmatter instead of HTML comments for Mintlify compatibility
+[[annotations]]
+path = "docs/contents/**/*.md"
+SPDX-FileCopyrightText = "2025 InOrbit, Inc."
+SPDX-License-Identifier = "MIT"
+SPDX-FileComment = "Documentation content (Mintlify-compatible)"
+
+# Documentation JSON config
+[[annotations]]
+path = "docs/contents/docs.json"
+SPDX-FileCopyrightText = "2025 InOrbit, Inc."
+SPDX-License-Identifier = "MIT"
+SPDX-FileComment = "Mintlify navigation configuration"
+
+# Mintlify build Makefile (has SPDX header but adding for completeness)
+[[annotations]]
+path = "docs/mintlify/Makefile"
+SPDX-FileCopyrightText = "2025 InOrbit, Inc."
+SPDX-License-Identifier = "MIT"
+SPDX-FileComment = "Mintlify build configuration"
+
+# Sphinx wrapper files (use {include} directives, minimal content)
+[[annotations]]
+path = "docs/sphinx/**/*.md"
+SPDX-FileCopyrightText = "2025 InOrbit, Inc."
+SPDX-License-Identifier = "MIT"
+SPDX-FileComment = "Sphinx documentation wrappers"

docs/configuration.md → docs/contents/configuration.md

@@ -1,18 +1,15 @@
-<!--
-SPDX-FileCopyrightText: 2025 InOrbit, Inc.
-
-SPDX-License-Identifier: MIT
--->
-
-# Configuration
+---
+title: "Configuration"
+description: "Configuration models and file formats for connectors"
+---
 
 The `inorbit-connector` framework uses Pydantic models for configuration, providing validation and type safety.
 
 ## ConnectorConfig
 
 The main configuration class is `ConnectorConfig`, which contains all settings for your connector. It includes a `fleet` field containing a list of `RobotConfig` entries.
 
-Connectors should subclass `inorbit_connector.models.ConnectorConfig` and define a `connector_config` field that contains the configuration for the connector. For more details see the {ref}`creating-a-custom-configuration` section below.
+Connectors should subclass `inorbit_connector.models.ConnectorConfig` and define a `connector_config` field that contains the configuration for the connector. For more details see the [Creating a Custom Configuration](#creating-a-custom-configuration) section below.
 
 ### Key Fields
 

docs/contents/docs.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "navigation": {
+    "products": [
+      {
+        "product": "Ground Control",
+        "tabs": [
+          {
+            "tab": "Connecting Devices",
+            "pages": [
+              {
+                "group": "Connector Framework",
+                "pages": [
+                  "ground-control/robot-integration/connector-framework/index",
+                  "ground-control/robot-integration/connector-framework/getting-started",
+                  {
+                    "group": "Usage",
+                    "pages": [
+                      "ground-control/robot-integration/connector-framework/usage/index",
+                      "ground-control/robot-integration/connector-framework/usage/single-robot",
+                      "ground-control/robot-integration/connector-framework/usage/fleet",
+                      "ground-control/robot-integration/connector-framework/usage/commands-handling"
+                    ]
+                  },
+                  "ground-control/robot-integration/connector-framework/configuration",
+                  "ground-control/robot-integration/connector-framework/publishing",
+                  {
+                    "group": "Specification",
+                    "pages": [
+                      "ground-control/robot-integration/connector-framework/specification/index",
+                      "ground-control/robot-integration/connector-framework/specification/connector",
+                      "ground-control/robot-integration/connector-framework/specification/models",
+                      "ground-control/robot-integration/connector-framework/specification/commands",
+                      "ground-control/robot-integration/connector-framework/specification/utils",
+                      "ground-control/robot-integration/connector-framework/specification/logging"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+
+

docs/getting-started.md → docs/contents/getting-started.md

@@ -1,10 +1,7 @@
-<!--
-SPDX-FileCopyrightText: 2025 InOrbit, Inc.
-
-SPDX-License-Identifier: MIT
--->
-
-# Getting Started
+---
+title: "Getting Started"
+description: "Installation and setup for the InOrbit Connector Framework"
+---
 
 ## Installation
 

docs/index.md → docs/contents/index.md

@@ -1,10 +1,7 @@
-<!--
-SPDX-FileCopyrightText: 2025 InOrbit, Inc.
-
-SPDX-License-Identifier: MIT
--->
-
-# inorbit-connector
+---
+title: "Connector Framework"
+description: "Python framework for developing InOrbit robot connectors"
+---
 
 A Python framework for developing *connectors* for the [InOrbit](https://inorbit.ai/) RobOps ecosystem.
 
@@ -31,21 +28,10 @@ Both connector types provide:
 - Python 3.10 or later
 - InOrbit account ([it's free to sign up!](https://control.inorbit.ai))
 
-```{toctree}
-:maxdepth: 2
-:hidden:
-
-getting-started
-specification/index
-usage/index
-configuration
-publishing
-```
-
 ## Documentation Sections
 
-- **Getting Started**: Installation, environment setup, and running a connector
-- **Specification**: Package-level specification of the connector API (what you can call and what you can override)
-- **Usage**: Detailed guides for implementing single-robot and fleet connectors
-- **Configuration**: Complete connector customization guide
-- **Publishing**: How to publish data to InOrbit
+- **Getting Started**: Installation, environment setup, and running a connector ([Getting Started](getting-started))
+- **Specification**: Package-level specification of the connector API ([Specification](specification/index))
+- **Usage**: Detailed guides for implementing single-robot and fleet connectors ([Usage](usage/index))
+- **Configuration**: Connector configuration models and file formats ([Configuration](configuration))
+- **Publishing**: How to publish data to InOrbit ([Publishing](publishing))

docs/publishing.md → docs/contents/publishing.md

@@ -1,10 +1,7 @@
-<!--
-SPDX-FileCopyrightText: 2025 InOrbit, Inc.
-
-SPDX-License-Identifier: MIT
--->
-
-# Publishing Data
+---
+title: "Publishing Data"
+description: "How to publish robot data to InOrbit"
+---
 
 The connector framework provides methods to publish various types of data to InOrbit. Both single-robot (`Connector`) and fleet (`FleetConnector`) connectors support publishing, with fleet connectors using methods prefixed with `publish_robot_*` that require a `robot_id` parameter.
 

docs/specification/commands.md → docs/contents/specification/commands.md

@@ -1,10 +1,7 @@
-<!--
-SPDX-FileCopyrightText: 2025 InOrbit, Inc.
-
-SPDX-License-Identifier: MIT
--->
-
-# Commands utilities
+---
+title: "Commands Utilities"
+description: "Command handling utilities specification"
+---
 
 This page specifies command handling helpers from `inorbit_connector.commands`.
 
@@ -46,7 +43,7 @@ These classes support type-safe parsing and validation of structured command par
 - `CommandModel` is a Pydantic `BaseModel` configured with `extra="forbid"`, and converts `ValidationError` into `CommandFailure`.
 - `ExcludeUnsetMixin` changes `model_dump()` default behavior to `exclude_unset=True` (useful when you want to emit only explicitly-provided fields).
 
-See {doc}`../usage/commands-handling` for end-to-end usage patterns.
+See [Commands Handling](../usage/commands-handling) for end-to-end usage patterns.
 
 ## Note: re-exports via `inorbit_connector.connector`