diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..122f691 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,55 @@ +# Builds MkDocs site from docs/ and deploys to GitHub Pages. +# +# One-time repo setup (maintainer): Settings → Pages → Build and deployment → +# Source: GitHub Actions. The first successful run publishes the site. +name: Deploy documentation to GitHub Pages + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: docs/requirements.txt + + - name: Install MkDocs + run: pip install -r docs/requirements.txt + + - name: Build site + run: mkdocs build --strict + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 0a70fe5..2539546 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,9 @@ web/node_modules/ .tools/ build/ dist/ + +# MkDocs (local `mkdocs build`; GitHub Pages uploads `site/` from CI only) +/site/ *.egg-info/ .coverage htmlcov/ diff --git a/CHANGELOG.md b/CHANGELOG.md index b6204d0..b69acc9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ This project follows [Semantic Versioning](https://semver.org/). From **v1.0.0** ### Added +- **Documentation (GitHub Pages):** workflow **`.github/workflows/pages.yml`** builds **`docs/`** with MkDocs Material on pushes to **`main`**; published URL on **`[project.urls] Documentation`**, README, **`DEVELOPMENT.md`**, and **`CONTRIBUTING.md`**. The static site includes a dismissible **Ask AI** banner (Perplexity / ChatGPT / repo) and a floating **Ask AI** shortcut (Perplexity with docs + repo context); no FlightDeck servers are involved. - **Web UI (`flightdeck serve`):** **`/#/settings`** for appearance (Light / Dark / System, **`flightdeck-theme`**); collapsible sidebar (**`flightdeck-sidebar-collapsed`**); **offline system font stack** (no remote font CSS); sidebar + favicon use **bundled** **`/assets/flightdeck-icon-*.png`** with stable **`GET /flightdeck-icon.png`** fallback; **`html[data-theme="dark"]`** tokens and Playwright **`web/e2e/`** (`smoke` icon checks, `theme.spec.ts`, `sidebar.spec.ts`). - **`flightdeck pricing check`** — reports **`flightdeck-bundled-*`** snapshot age vs **`--max-age-days`** (default **90**); **`--fail`** for CI. **`release diff`** / **`POST /v1/diff`** append **`pricing.warnings`** when bundled snapshots exceed the same age threshold. - **`flightdeck.integrations.telemetry.configure_otel_tracing()`** — optional OTLP HTTP **`TracerProvider`** wiring when the **`telemetry`** extra is installed (see **`docs/sdk-integrations.md`**). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24081f1..57f04e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,6 +55,10 @@ If you change **`pyproject.toml`** dependencies, run **`uv lock`** and commit ** Details, Windows notes, and doctrine: **`AGENTS.md`** (Verification), **`DEVELOPMENT.md`**, **`web/README.md`**. +## GitHub Pages (maintainers) + +The **Deploy documentation to GitHub Pages** workflow publishes **`docs/`** on pushes to **`main`**. In the GitHub repo, use **Settings → Pages → Build and deployment → Source: GitHub Actions** so the workflow can attach the **`github-pages`** environment. The live URL is linked from the root **`README.md`** and **`pyproject.toml`** **`Documentation`** URL. + ## Private files and pushing to GitHub Do not commit credentials, customer data, internal strategy docs, or local ledger data. The repo ignores **`.flightdeck/`**, **`.env*`**, optional **`private/`** / **`secrets/`**, and common key/credential patterns—see **`.gitignore`** and **[SECURITY.md](SECURITY.md)**. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index f1d2c5c..ece000c 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -282,3 +282,14 @@ Use **`uv run python -m pytest`** from the repo root so imports like **`from tes | `VITE_FLIGHTDECK_LOCAL_API_TOKEN` | Web dev server | Build-time variable for the React UI dev server (Vite). Copy `web/.env.example` → `web/.env.local` to set it when testing mutations through `npm run dev` against a token-protected server. | | `VITE_DEV_PROXY_TARGET` | Web dev server | Overrides the Vite proxy target for `/v1` (default: `http://127.0.0.1:8765`). | | `TMPDIR` / `TEMP` / `TMP` | Tests / OS | Standard temp directory environment variables. Set any of these to a repo-local `.tmp/` path if the OS default is restricted or permissions cause pytest failures. | + +## Documentation site (MkDocs) + +The Markdown under **`docs/`** is also built as a static site for **[GitHub Pages](https://flightdeckdev.github.io/flightdeck/)** (workflow **`.github/workflows/pages.yml`**). To preview locally: + +```bash +pip install -r docs/requirements.txt +mkdocs serve +``` + +Then open the URL MkDocs prints (usually **http://127.0.0.1:8000/**). The build output directory **`site/`** is gitignored; CI uploads it as the Pages artifact. diff --git a/README.md b/README.md index 8501379..8f4cf48 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,8 @@ Bundled pricing from `init` is a **convenience snapshot**—`flightdeck pricing ## Documentation +**Published site (GitHub Pages):** [flightdeckdev.github.io/flightdeck](https://flightdeckdev.github.io/flightdeck/) — built from `docs/` on each push to `main` (`.github/workflows/pages.yml`). Enable **Pages → GitHub Actions** in the repository settings if the site is not live yet. + | Area | Links | |------|--------| | CLI | [docs/cli.md](docs/cli.md) | diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c9e908c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,33 @@ +# FlightDeck documentation + +FlightDeck helps teams **ship AI agents safely** with **release diffs**, **runtime evidence**, and **policy gates**. + +This site mirrors the Markdown guides in the [flightdeck repository](https://github.com/flightdeckdev/flightdeck). Use the navigation on the left for the full reference. Repository-only pages (for example `SECURITY.md` at the repo root) are linked from the guides where relevant—open those on GitHub when you need the latest wording. + +## Ask AI + +Use the **dismissible banner** at the top to open **Perplexity** or **ChatGPT** in a new tab. Mention this documentation site or the GitHub repo so answers stay grounded in the real product surface (CLI, `release.yaml`, HTTP `/v1` routes, policy). + +## Quick links + +| Topic | Doc | +|--------|-----| +| Commands, flags, exit codes | [CLI reference](cli.md) | +| `flightdeck serve` JSON API | [HTTP API](http-api.md) | +| Diff, promote, rollback, SQLite | [Operations & policy](operations-and-policy.md) | +| `release.yaml`, workspace config | [Release artifact](release-artifact.md) | +| Optional pricing catalog YAML | [Pricing catalog](pricing-catalog.md) | +| `flightdeck` Python client | [Python SDK](sdk.md) | +| Experimental adoption hooks | [SDK integrations](sdk-integrations.md) | +| Shipped web UI vs roadmap | [Web UI](web-ui.md) · [UI roadmap](ui-roadmap.md) | +| Common failures | [Troubleshooting](troubleshooting.md) | + +## Install (local) + +```bash +uv sync --extra dev +uv run flightdeck --help +uv run flightdeck-quickstart-verify +``` + +See [DEVELOPMENT.md](https://github.com/flightdeckdev/flightdeck/blob/main/DEVELOPMENT.md) on GitHub for full contributor setup, web bundle rebuild, and CI parity. diff --git a/docs/javascripts/ask-ai.js b/docs/javascripts/ask-ai.js new file mode 100644 index 0000000..5031275 --- /dev/null +++ b/docs/javascripts/ask-ai.js @@ -0,0 +1,31 @@ +/* Floating “Ask AI” — opens Perplexity with repo + docs context (no FlightDeck servers). */ +(function () { + var url = + "https://www.perplexity.ai/search?q=" + + encodeURIComponent( + "FlightDeck: AI agent release governance (CLI, SQLite ledger, policy gates, diff, promote). Official docs site https://flightdeckdev.github.io/flightdeck/ and source https://github.com/flightdeckdev/flightdeck — answer using those when possible." + ); + + function addButton() { + if (document.getElementById("fd-floating-ask-ai")) { + return; + } + var a = document.createElement("a"); + a.id = "fd-floating-ask-ai"; + a.href = url; + a.target = "_blank"; + a.rel = "noopener noreferrer"; + a.textContent = "Ask AI"; + a.setAttribute( + "aria-label", + "Ask AI about FlightDeck in Perplexity (new tab)" + ); + document.body.appendChild(a); + } + + if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", addButton); + } else { + addButton(); + } +})(); diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..d9aaaa6 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +# Pinned for reproducible GitHub Pages builds (not part of the Python package). +mkdocs==1.6.1 +mkdocs-material==9.6.14 diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..1c9a67b --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,30 @@ +/* Slightly stronger “Ask AI” strip (Material theme `extra.announce`) */ +.md-banner { + font-size: 0.85rem; +} + +.md-banner a { + font-weight: 600; + text-decoration: underline; + text-underline-offset: 2px; +} + +/* Floating Perplexity shortcut (paired with docs/javascripts/ask-ai.js) */ +#fd-floating-ask-ai { + position: fixed; + bottom: 1.25rem; + right: 1.25rem; + z-index: 200; + padding: 0.45rem 1rem; + border-radius: 999px; + background: var(--md-primary-fg-color); + color: var(--md-primary-bg-color) !important; + font-weight: 600; + font-size: 0.8rem; + box-shadow: var(--md-shadow-z2); + text-decoration: none !important; +} + +#fd-floating-ask-ai:hover { + opacity: 0.92; +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..7cb61d1 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,82 @@ +site_name: FlightDeck documentation +site_description: Release diffs, runtime evidence, and policy gates for AI agents. +site_url: https://flightdeckdev.github.io/flightdeck/ +repo_url: https://github.com/flightdeckdev/flightdeck +repo_name: flightdeckdev/flightdeck +edit_uri: edit/main/docs/ + +docs_dir: docs +site_dir: site + +strict: true + +# Guides intentionally link to repo-root files (SECURITY.md, schemas/, …) for GitHub +# readers; those paths are not copied into the MkDocs tree. +validation: + links: + not_found: ignore + anchors: ignore + +nav: + - Home: index.md + - CLI: cli.md + - HTTP API: http-api.md + - Operations & policy: operations-and-policy.md + - Release artifact: release-artifact.md + - Pricing catalog: pricing-catalog.md + - Python SDK: sdk.md + - SDK integrations: sdk-integrations.md + - Web UI: web-ui.md + - UI roadmap: ui-roadmap.md + - Troubleshooting: troubleshooting.md + +theme: + name: material + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.expand + - navigation.sections + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + +plugins: + - search + +markdown_extensions: + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - tables + - toc: + permalink: true + +extra: + generator: false + # Dismissible strip with outbound “Ask AI” helpers (no FlightDeck backend). + announce: >- + Ask AI about FlightDeck (paste the question after the page loads): + Perplexity + · + ChatGPT + · + Repository + +extra_css: + - stylesheets/extra.css + +extra_javascript: + - javascripts/ask-ai.js diff --git a/pyproject.toml b/pyproject.toml index 5faa96e..552ebe7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -68,6 +68,7 @@ integrations-ci = [ [project.urls] Homepage = "https://github.com/flightdeckdev/flightdeck" +Documentation = "https://flightdeckdev.github.io/flightdeck/" Repository = "https://github.com/flightdeckdev/flightdeck" Issues = "https://github.com/flightdeckdev/flightdeck/issues" Changelog = "https://github.com/flightdeckdev/flightdeck/blob/main/CHANGELOG.md"