Docs first draft

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - docs-first-draft
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material mkdocs-include-markdown-plugin "mkdocstrings[python]" pymdown-extensions
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build site
+        run: mkdocs build --config-file docs/mkdocs.yml
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

docs/README.md

@@ -0,0 +1,30 @@
+# OpenEnv docs workflow
+
+Use this guide to preview and build the MkDocs site that lives under `docs/`.
+
+## 1. Install dependencies
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install mkdocs-material mkdocs-include-markdown-plugin "mkdocstrings[python]" pymdown-extensions
+```
+
+The packages mirror what the GitHub Pages workflow installs, so local builds match CI.
+
+## 2. Run the live preview server
+
+```bash
+mkdocs serve --config-file docs/mkdocs.yml
+```
+
+The site is served at `http://127.0.0.1:8000/` with automatic reloads whenever files in `docs/` or `docs/mkdocs.yml` change.
+
+## 3. Produce the production build
+
+```bash
+mkdocs build --config-file docs/mkdocs.yml --clean --site-dir site
+```
+
+This regenerates the static HTML into `site/`, matching `.github/workflows/docs.yml`. Inspect the output locally.
+

docs/cli.md

@@ -0,0 +1,37 @@
+# CLI (`openenv_cli`)
+
+The `openenv` CLI provides a set of commands for building, validating, and pushing environments to Hugging Face Spaces or a custom Docker registry. For an end-to-end tutorial on building environments with OpenEnv, see the [building an environment](environment-builder.md) guide.
+
+## `openenv init`
+
+::: openenv_cli.commands.init
+
+## `openenv build`
+
+::: openenv_cli.commands.build
+
+## `openenv validate`
+
+::: openenv_cli.commands.validate
+
+## `openenv push`
+
+::: openenv_cli.commands.push
+
+## `openenv serve`
+
+::: openenv_cli.commands.serve
+
+# API Reference
+
+## Entry point
+
+::: openenv_cli.__main__
+
+## CLI helpers
+
+::: openenv_cli._cli_utils
+
+## Validation utilities
+
+::: openenv_cli._validation

docs/core.md

@@ -0,0 +1,29 @@
+# Core API Reference
+
+The `openenv-core` package provides the core abstractions for building and running environments. For an end-to-end tutorial on building environments with OpenEnv, see the [building an environment](environment-builder.md) guide.
+
+## Core runtime (`core`)
+
+### Environment server primitives
+
+::: core.env_server.interfaces
+
+### HTTP server utilities
+
+::: core.env_server.http_server
+
+### Web interface helpers
+
+::: core.env_server.web_interface
+
+### Client contracts
+
+::: core.http_env_client
+
+### Shared dataclasses
+
+::: core.client_types
+
+### Container providers
+
+::: core.containers.runtime.providers