diff --git a/README.md b/README.md index f7513a4..712da6d 100644 --- a/README.md +++ b/README.md @@ -52,35 +52,37 @@ The site is available at `http://127.0.0.1:8000`. Changes to `docs/index.md` or ## Private repositories -If a tool repo is private, export a GitHub personal access token before building: +To build locally, use Git credentials with read access to the source +repositories. The GitHub CLI credential helper can reuse your existing login. ```bash -export GithubAccessToken=your_token_here -mkdocs serve +gh auth setup-git +mkdocs build --strict ``` -The GitHub Actions workflow reads the token from a repository secret named `GH_TOKEN` and passes it only to the build-and-deploy step in [.github/workflows/scheduled-deploy.yml](.github/workflows/scheduled-deploy.yml). The deploy token needs read-only access to the private `matt_lisa` repository. +The GitHub Actions workflow maps the portal repository's `GH_TOKEN` secret to +`GithubAccessToken` during the build. Use a token with **Contents: Read-only** +access to the following Unity Environmental University repositories. -## XR Education exports +- `matt_lisa` +- `Summit` +- `Trailhead` +- `XR-Tools` +- `XR-Tools-Updater-Service` -The public portal imports Waste Management directly from its public -repository, including its interactive waypoint explainer. The four private -XR projects publish reviewed copies of selected pages under -[`docs/xr-education/`](docs/xr-education/). The portal build uses those copies -without needing access to the private XR repositories. +Verify the new credential can read all five before replacing the current +secret in **Settings → Secrets and variables → Actions**. -To update a private XR guide: +## XR Education source docs -1. Make the edit under `docs/portal/` in the source repository. Preview it - there with `mkdocs build --strict` using this portal's requirements. -2. Merge the source change into its `main` branch. -3. From this repository, run `python3 scripts/sync-xr-docs.py` with Git - credentials that can read the four source repositories. If you add an - exported page, list it in the script and this repository's navigation. -4. Review the exported changes for public release. Commit them with - [the source revisions](xr-education-sources.json) and merge the portal - change to rebuild the site. +Write Summit, Trailhead, XR Tools, and XR Tools Updater Service guides in +`docs/portal/` in the respective repositories. The portal imports that +directory from each repository's `main` branch. Add new pages to that +repository's `mkdocs.yml` navigation and preview them with +`mkdocs build --strict` using this portal's requirements. Every file in +`docs/portal/` is eligible for publication on the public portal. -The refresh copies only the listed pages. It leaves the current copies intact -if any source fetch fails. The portal config enables Mermaid for both exports -and imported pages. +Waste Management uses its public `docs/` directory, including the +interactive waypoint explainer. The portal config enables Mermaid for all +imported guides. After a source change merges, the next scheduled or manual +portal build picks it up. diff --git a/docs/xr-education/summit/data.md b/docs/xr-education/summit/data.md deleted file mode 100644 index 235915e..0000000 --- a/docs/xr-education/summit/data.md +++ /dev/null @@ -1,46 +0,0 @@ -# Summit data and reporting reference - -## Data Summit collects - -| Record | What it describes | Where to look | -| --- | --- | --- | -| Session | A play interval for an app, with version, player ID, and session metadata | Sessions | -| Event | A named action with optional properties, measurements, or a numeric value | Events Explorer | -| Performance sample | Client FPS and memory observations | Performance | -| Hardware profile | Device information associated with a player across sessions | Users | -| Feedback response | Answers keyed by the fields of a form or supplied by the game | Feedback | -| Trailhead summary | A recording ID, metadata, and a replay URL when configured | Sessions or Users | - -An event with an unknown session ID or a session ID from a different app can -still appear in Events Explorer. Summit stores that event without a session -association. For an integrated replay, the UUID in `summit_session_id` identifies -the Summit session, while the Trailhead recording has its own UUID. - -## Where to answer a question - -| Question | View | -| --- | --- | -| What happened around a specific action? | Open the session and inspect its event timeline. Follow its replay link if one is available. | -| At which step do players stop a sequence? | Build a funnel from the ordered event names. | -| Does frame rate vary across sessions? | Compare FPS in Performance and inspect specific players in Users. | -| What did players report? | Filter Feedback and inspect response details and per-question rollups. | -| Which fields recur in a weekly report? | Build a custom report from stored fields, save the definition, and export its results as CSV. | - -## API entry points - -Paths are relative to the application base path. Game ingestion uses the -game's app key in `x-api-key`. Programmatic dashboard queries and app management -use the dashboard API key. Browser access uses a signed-in dashboard account. - -| Operation | Route | -| --- | --- | -| Start or end a session | `POST /api/ingest/session/start` or `POST /api/ingest/session/end` | -| Record events or samples | `POST /api/ingest` or `POST /api/ingest/batch` | -| Send device details | `POST /api/ingest/hardware` | -| Load a feedback form or send answers | `GET /api/feedback/forms` or `POST /api/ingest/feedback` | -| Query recorded events | `POST /api/query/events` | -| Run a custom report definition | `POST /api/reports/run` | - -See the [full API table](https://github.com/Unity-Environmental-University/Summit#api-endpoints) -and the [request schemas](https://github.com/Unity-Environmental-University/Summit/blob/main/dashboard/lib/validation.ts) -for route-specific fields. diff --git a/docs/xr-education/summit/first-event.md b/docs/xr-education/summit/first-event.md deleted file mode 100644 index b49301b..0000000 --- a/docs/xr-education/summit/first-event.md +++ /dev/null @@ -1,62 +0,0 @@ -# Send your first event - -Create a disposable app and send an event you can find in Events Explorer. -Use the Docker stack so the service runs with the same `/summit` path as a -production build. - -## Start Summit - -1. From the repository root, copy `.env.example` to `.env`. -2. Set `DB_PASSWORD`, `DASHBOARD_API_KEY`, and `SUMMIT_ADMIN_PASSWORD` in `.env`. -3. Run `docker compose up -d`. -4. Open [the local dashboard](http://localhost:8088/summit/dashboard) and sign - in with the bootstrap administrator account. - -On a new stack, PostgreSQL initializes the schema. For database upgrades, follow -the [migration notes in the repository](https://github.com/Unity-Environmental-University/Summit#readme) -for the database you are upgrading. - -## Create an app and session - -Run these commands from a terminal. Set `DASHBOARD_API_KEY` in your shell to -the value from the local `.env` file before you begin. - -```bash -base=http://localhost:8088/summit - -curl --fail-with-body -sS "$base/api/apps" \ - -H "Content-Type: application/json" \ - -H "x-api-key: $DASHBOARD_API_KEY" \ - -d '{"name":"Documentation smoke test"}' -``` - -Set `APP_API_KEY` in your shell to the returned `api_key`. Run the next request -with the app key. The response includes the new session's `id`. - -```bash -curl --fail-with-body -sS "$base/api/ingest/session/start" \ - -H "Content-Type: application/json" \ - -H "x-api-key: $APP_API_KEY" \ - -d '{"user_id":"docs-player","app_version":"0.0.1"}' -``` - -## Track a checkpoint - -Set `SESSION_ID` to the returned `id`. Send one event to that session. - -```bash -curl --fail-with-body -sS "$base/api/ingest" \ - -H "Content-Type: application/json" \ - -H "x-api-key: $APP_API_KEY" \ - --data-binary @- <|Events and performance| Ingest["Summit ingestion API"] - Game -->|Session lifecycle and feedback| Ingest - Ingest --> DB[("PostgreSQL and TimescaleDB")] - Trailhead["Trailhead"] -->|Recording summary| Ingest - DB --> Dashboard["Summit dashboard and reports"] - Dashboard -->|Replay link| Trailhead -``` - -The API validates game data before writing it to PostgreSQL. TimescaleDB -organizes time-series events and performance samples. Dashboard queries use -that data for individual sessions and aggregate views. - -A player can have multiple sessions. A session can have multiple Trailhead -recordings. Summit stores a summary and replay link for each synced recording. -Trailhead keeps the frames and events that make up the replay. - -## Source map - -| Area | Location | -| --- | --- | -| Game instrumentation | [Unity client and API examples](https://github.com/Unity-Environmental-University/Summit/tree/main/clients/unity) | -| Next.js dashboard and API | [Dashboard source](https://github.com/Unity-Environmental-University/Summit/tree/main/dashboard) | -| PostgreSQL schema | [SQL migrations](https://github.com/Unity-Environmental-University/Summit/tree/main/backend/migrations) | -| Local setup and branch promotion | [Project README](https://github.com/Unity-Environmental-University/Summit#readme) | diff --git a/docs/xr-education/summit/unity.md b/docs/xr-education/summit/unity.md deleted file mode 100644 index 0320ef0..0000000 --- a/docs/xr-education/summit/unity.md +++ /dev/null @@ -1,51 +0,0 @@ -# Connect a Unity game to Summit - -Install [`SummitAnalytics.cs`](https://github.com/Unity-Environmental-University/Summit/blob/main/clients/unity/SummitAnalytics.cs) -on a persistent GameObject. Set `apiUrl` to the Summit origin and `apiKey` to the -game's app key. `SummitAnalytics` supplies the `/summit` path itself. Test -the network flow in a player build because analytics uploads are disabled in -the Unity Editor. - -## Instrument a session - -Use a stable pseudonymous player ID. Call `Identify` before you start a session -or queue that player's first event. - -```csharp -analytics.Identify(playerId); -analytics.StartSession(appVersion: Application.version); -analytics.Track("checkpoint_reached", numericValue: 1f); -``` - -Use the same event name for every occurrence of the same action. Put the level, -checkpoint, or other changing context in `properties`. Put named numeric values, -such as elapsed seconds, in `properties.measurements`. Send durable device -details with `SendHardwareProfile()`. Call `EndSession()` where your game marks -the end of the play session. - -## Link a Trailhead replay - -Subscribe to `OnSessionStarted` before you call `StartSession`. Pass the -received ID and the same player ID to Trailhead's `LinkSummitSession`. - -```mermaid -sequenceDiagram - participant G as Unity game - participant S as Summit - participant T as Trailhead - G->>S: Start a session with the player ID - S-->>G: Return the session UUID - Note over G: OnSessionStarted links the recorder - G->>T: Upload recording with Summit session UUID - T-->>G: Accept the recording - T->>S: Sync recording summary and replay URL - Note over S,T: Opening replay loads the frames in Trailhead -``` - -The recorder can start while Summit is still opening the session. -`OnSessionStarted` runs when Summit issues an ID, including after a successful -retry. Check for `summit_session_id` on the saved recording if it appears in -Trailhead but is missing from the Summit session. - -For the full SDK, including the Virtual Forest handshake and player feedback -components, use the [Unity client guide](https://github.com/Unity-Environmental-University/Summit/tree/main/clients/unity#readme). diff --git a/docs/xr-education/trailhead/first-replay.md b/docs/xr-education/trailhead/first-replay.md deleted file mode 100644 index 808396e..0000000 --- a/docs/xr-education/trailhead/first-replay.md +++ /dev/null @@ -1,40 +0,0 @@ -# Replay a sample recording - -Use the repository's sample recording to check ingestion, storage, and the 3D -viewer together. The sample has positions and events you can inspect as soon as -the upload finishes. - -## Start Trailhead - -1. From the repository root, copy `.env.example` to `.env`. -2. Set `DB_PASSWORD` and `API_KEY` to local test values. -3. Run `docker compose up --build -d`. -4. Open [the recordings gallery](http://localhost:8087/trailhead/recordings). - -Compose starts PostgreSQL, applies the Trailhead migrations on application -startup, and mounts a volume for recording files. - -## Upload the fixture - -Set `API_KEY` in your shell to the value from the local `.env` file. Run the -command from the repository root. - -```bash -base=http://localhost:8087/trailhead - -curl --fail-with-body -sS "$base/api/recordings" \ - -H "Content-Type: application/json" \ - -H "x-api-key: $API_KEY" \ - --data-binary @fixtures/sample-recording.json -``` - -The response contains the new recording's `id`. Open -`http://localhost:8087/trailhead/recording?id=` with that value. - -Press **Play** and scrub backward to an earlier moment. Use the subject panel -to see what Trailhead tracked, and use the events panel to inspect a timestamp. -Reload the gallery to see the saved recording. - -If the request returns `401`, check that the key in the shell matches the one -the container received. Check the `/trailhead` prefix if the request returns -`404`. Trailhead uses that prefix for both development and production builds. diff --git a/docs/xr-education/trailhead/index.md b/docs/xr-education/trailhead/index.md deleted file mode 100644 index 7b7392a..0000000 --- a/docs/xr-education/trailhead/index.md +++ /dev/null @@ -1,34 +0,0 @@ -# Trailhead - -Trailhead records the motion and events of a Unity session and replays them in -a browser. Use it to see where a player moved, what a tracked object was doing, -and which events occurred around a point in the recording. - -[Replay the bundled sample](first-replay.md) to try the viewer. -[Record from Unity](unity.md) to instrument a scene, or see the -[recording and sync reference](recording.md) for upload and storage details. - -## From a Unity scene to the replay viewer - -```mermaid -flowchart LR - Game["Unity game"] -->|Whole recording or segments| API["Trailhead ingest"] - API -->|Recording JSON| Files[("Recording volume")] - API -->|Metadata and status| DB[("PostgreSQL")] - DB -->|Recording listing| Viewer["Trailhead dashboard"] - Files -->|Frames and events| Viewer - API -->|Optional recording summary| Summit["Summit"] - Summit -->|Replay link| Viewer -``` - -The dashboard reads metadata from PostgreSQL and loads the recording JSON -from disk for playback. A summary in Summit can link back to that replay. - -## Source map - -| Area | Location | -| --- | --- | -| Unity recorder | [Client example and API guide](https://github.com/Unity-Environmental-University/Trailhead/tree/main/clients/unity) | -| Replay controls and view | [Viewer components](https://github.com/Unity-Environmental-University/Trailhead/tree/main/dashboard/components/recording-viewer) | -| Payload structure | [Recording types](https://github.com/Unity-Environmental-University/Trailhead/blob/main/dashboard/lib/recording-types.ts) | -| Database setup | [SQL migrations](https://github.com/Unity-Environmental-University/Trailhead/tree/main/backend/migrations) | diff --git a/docs/xr-education/trailhead/recording.md b/docs/xr-education/trailhead/recording.md deleted file mode 100644 index 58b8114..0000000 --- a/docs/xr-education/trailhead/recording.md +++ /dev/null @@ -1,52 +0,0 @@ -# Recording and sync reference - -## Ingest routes - -Trailhead uses the `/trailhead` base path. Both upload routes take the Trailhead -`API_KEY` in `x-api-key` and accept JSON or gzip-compressed JSON with -`Content-Encoding: gzip`. - -| Mode | Route after the base path | Recording ID | State | -| --- | --- | --- | --- | -| Whole recording | `POST /api/recordings` | Trailhead assigns it and returns it with `201` | Finalized on acceptance | -| Incremental | `POST /api/recordings/{id}/segments` | The client chooses a UUID before the first request | Playable after upload, finalized by a segment with `final: true` | -| Replay | `GET /recording?id={id}` | The same ID used by the gallery and Summit link | Loads the saved frames and events | - -The default body ceilings are 16 MiB for a whole recording and 2 MiB per -segment. Trailhead applies limits to the decoded JSON as well. The whole-file -route returns `422` if its recorded duration is under 20 seconds or its recorded -move count is zero, when those values are supplied. The incremental route can -report `discarded: true` for those conditions on finalization. - -## Incremental recordings - -Each segment has a stable `segmentId` for retries. Send only new frames and -events, address subjects by index, and set `isNew` on a newly introduced -subject. A retried segment reuses its original ID. The server also drops frames -and events repeated by overlapping segments. - -```mermaid -stateDiagram-v2 - [*] --> Recording: First segment - Recording --> Recording: More accepted segments - Recording --> Finalized: Accepted final segment - Recording --> Discarded: Final segment fails duration or move filter -``` - -The first segment can also be the final segment. An interrupted client can -leave a playable recording in progress. PostgreSQL tracks recording state and -segment IDs, while the recording volume holds the JSON used in the viewer. - -## Summit sync settings - -| Setting | Purpose | -| --- | --- | -| `SUMMIT_API_URL` | Summit base URL, including `/summit` for the Docker or production build | -| `SUMMIT_APP_API_KEY` | Summit app key Trailhead uses to submit the summary | -| `TRAILHEAD_PUBLIC_URL` | Browser-facing Trailhead base URL, including `/trailhead`, used to construct replay links | -| `SUMMIT_SYNC_URL` | Optional full URL override for incremental upload syncs | - -Trailhead submits summaries after accepting a whole recording or a segment. -The sync is best effort. A recording can play in Trailhead while its summary is -missing from Summit. Check the Summit URL and key, and confirm that the -recording's `summit_session_id` belongs to an existing Summit session. diff --git a/docs/xr-education/trailhead/unity.md b/docs/xr-education/trailhead/unity.md deleted file mode 100644 index 0d5bbe9..0000000 --- a/docs/xr-education/trailhead/unity.md +++ /dev/null @@ -1,35 +0,0 @@ -# Record from Unity - -Add [`TrailheadRecorder.cs`](https://github.com/Unity-Environmental-University/Trailhead/blob/main/clients/unity/TrailheadRecorder.cs) -to a persistent GameObject. Configure `apiUrl` with the Trailhead base URL, -including `/trailhead`. Set `apiKey` to the server's recording upload key. -The example logs the payload size in the Editor. Run a player build to upload. - -## Track the objects that explain a session - -1. Call `Identify(playerId)` with a stable pseudonymous ID. -2. Call `StartRecording("Forest walkthrough")`. -3. Call `AddSubject("Player", playerCamera.transform)` and save the returned index. -4. Mark a meaningful moment with `AddSubjectEvent(playerIndex, "Checkpoint reached")`. -5. Call `FinishRecording()` when play ends. - -The subject index identifies the tracked object, even if other subjects have the -same name. Use `AddEvent` for events that apply to the entire recording and -`SetMetadata` for context such as the game mode. Use `ClearSubjects` between -sessions when each session registers its own objects. - -Subscribe to `OnUploadComplete` before finishing the recording. If it returns -an ID, open `GetReplayUrl(id)` in the browser. The example client sends one -complete file. Clients that need to save progress during browser play can use -the [segmented upload route](recording.md#ingest-routes). - -## Keep the Summit session attached - -When Summit and Trailhead run in the same game, use the same player ID for -both. Subscribe to Summit's `OnSessionStarted` before starting its session. -Call Trailhead's `LinkSummitSession(sessionId, playerId)` with the ID from the -callback. When the server syncs the recording summary, Summit can attach it -to the original session. - -See the [Unity recorder guide](https://github.com/Unity-Environmental-University/Trailhead/tree/main/clients/unity#readme) -for render metadata and a complete code example. diff --git a/docs/xr-education/xr-tools-updater-service/index.md b/docs/xr-education/xr-tools-updater-service/index.md deleted file mode 100644 index c0305e2..0000000 --- a/docs/xr-education/xr-tools-updater-service/index.md +++ /dev/null @@ -1,26 +0,0 @@ -# XR Tools Updater Service - -The updater service distributes signed XR Tools updates. Release CI sends a -Tauri manifest and platform bundle. An installed app asks whether it has an -update for its platform and current version. - -```mermaid -sequenceDiagram - participant C as XR Tools release workflow - participant U as Updater service - participant V as Release volume - participant A as Installed XR Tools app - C->>U: Send manifest and signed bundle - U->>V: Store artifacts and update latest manifest - A->>U: Check with target, architecture, and version - U-->>A: Return download URL and signature for a newer build - A->>U: Download the bundle - Note over A: Tauri verifies the signature before installation -``` - -The service rewrites the manifest's download URLs to point at its hosted -artifacts. Uploads for the same version can add platform entries to the version's -manifest. The app-level manifest determines which version clients see. - -See [Check an updater release](verify.md) for the API and a readiness check. -For server setup, use the [repository README](https://github.com/Unity-Environmental-University/XR-Tools-Updater-Service#readme). diff --git a/docs/xr-education/xr-tools-updater-service/verify.md b/docs/xr-education/xr-tools-updater-service/verify.md deleted file mode 100644 index d6efe0d..0000000 --- a/docs/xr-education/xr-tools-updater-service/verify.md +++ /dev/null @@ -1,41 +0,0 @@ -# Check an updater release - -## Read the manifest and check the platform - -Set `UPDATER_URL` to the HTTPS service URL for a test environment. Check that -the service responds, then inspect the manifest for the app. - -```sh -curl --fail-with-body -sS "$UPDATER_URL/health" -curl --fail-with-body -sS "$UPDATER_URL/api/apps/xr-tools/static/latest.json" -``` - -If the environment requires client authentication, send the configured bearer -token with the manifest, update-check, and download requests. - -Choose a version lower than the manifest version. For example, if the manifest -promotes a version above `3.0.0`, check the Apple Silicon entry this way. - -```sh -curl --fail-with-body -i "$UPDATER_URL/api/apps/xr-tools/check/darwin/aarch64/3.0.0" -``` - -Expect `200` with a version, download URL, and signature when a newer bundle -exists for that platform. Repeat with the manifest version and expect -`204`. A newer version without a bundle for the requested platform returns -`404`. Confirm that each expected platform is present after release jobs finish. - -## Service reference - -| Route | Purpose | -| --- | --- | -| `GET /health` | Confirm the server can open its data directory | -| `POST /api/apps/{appId}/releases` | Accept a multipart manifest and its referenced files using the upload bearer token | -| `GET /api/apps/{appId}/static/latest.json` | Read the latest manifest across platforms | -| `GET /api/apps/{appId}/check/{target}/{arch}/{currentVersion}` | Get a newer bundle entry for one platform | -| `GET /download/{appId}/{version}/{asset}` | Download a stored release artifact | - -`DATA_DIR` is the persistent storage root. Set `BASE_URL` to the HTTPS origin -that clients use to reach the service, so the manifest's download URLs resolve -from the desktop app. `UPLOAD_TOKEN` authorizes release CI. The optional -`CLIENT_AUTH_TOKEN` applies to manifest reads, update checks, and downloads. diff --git a/docs/xr-education/xr-tools/deploy.md b/docs/xr-education/xr-tools/deploy.md deleted file mode 100644 index f9e135c..0000000 --- a/docs/xr-education/xr-tools/deploy.md +++ /dev/null @@ -1,22 +0,0 @@ -# Deploy a test build - -Use **FTP Deploy** to publish an XR web build to a test destination. Start -with a build folder that already runs locally. - -1. Open **FTP Deploy** in the desktop app. -2. Choose the local build folder. -3. Choose a destination in the **test** group. -4. Enter the credentials for the destination. -5. Select **Upload build**. -6. After the upload finishes, open the test site and check that it loads - the expected build and its assets. - -The Rust backend validates the target and local build before uploading. -It uploads into a staging folder and promotes that folder after the upload -succeeds. When a previous build exists, the server keeps it during promotion -so recovery can restore it if a rename fails. - -If the upload fails during a rename, read the recovery paths in the app's -error and confirm which build is live before retrying. If the TLS connection -fails, check that the configured host matches the certificate. The app requires -explicit FTPS with an encrypted data connection. diff --git a/docs/xr-education/xr-tools/development.md b/docs/xr-education/xr-tools/development.md deleted file mode 100644 index 3e871cf..0000000 --- a/docs/xr-education/xr-tools/development.md +++ /dev/null @@ -1,35 +0,0 @@ -# Develop and release XR Tools - -## Run the desktop app - -Install Node.js, Rust, and the native prerequisites for Tauri on your -platform. Run these commands from the repository root. - -```sh -npm ci -npm run dev -``` - -Use `npm run build` to produce a desktop bundle. Use `npm run web:dev` for -Vite-only interface work and the desktop window to exercise commands that -call Rust. - -| Area | Source | -| --- | --- | -| Tool interface and update prompt | [`src/main.js`](https://github.com/Unity-Environmental-University/XR-Tools/blob/main/src/main.js) | -| Native commands and VCS integration | [`src-tauri/src/tools/`](https://github.com/Unity-Environmental-University/XR-Tools/tree/main/src-tauri/src/tools) | -| Installers and signed updater bundles | [Release workflow](https://github.com/Unity-Environmental-University/XR-Tools/blob/main/.github/workflows/release.yml) | - -## Verify a release - -1. Run **Release** from the repository's Actions tab with the intended version. -2. Check the GitHub release for the Linux, Windows, and macOS installers. -3. Check the updater service for the Windows x86-64 and Apple Silicon bundles. -4. Open an older compatible desktop build. On launch, check that it offers - the new version, then install it and confirm the app reports the new version. - -The workflow points the packaged app at the configured HTTPS updater service. -The app verifies the downloaded update against its embedded public key. Keep -the matching signing key available to the release workflow. See the -[repository setup instructions](https://github.com/Unity-Environmental-University/XR-Tools#auto-updates) -for local updater testing and GitHub secret names. diff --git a/docs/xr-education/xr-tools/index.md b/docs/xr-education/xr-tools/index.md deleted file mode 100644 index 4aaa40b..0000000 --- a/docs/xr-education/xr-tools/index.md +++ /dev/null @@ -1,34 +0,0 @@ -# XR Tools - -XR Tools is a Tauri desktop app for the people who build and publish XR -experiences. It can upload a web build over FTPS, generate commit and changelog -drafts, and prepare a Gource visualization of a repository's history. - -## Choose a tool - -| Task | Tool | Requirements | -| --- | --- | --- | -| Upload a web build | FTP Deploy | A local build, hosting credentials, and a destination | -| Calculate biweekly pay dates | Pay Dates | The latest pay date and the number of years | -| Draft a Plastic SCM commit message | AI Commit | `cm` on `PATH` and an OpenAI API key | -| Visualize Git or Plastic SCM history | Gource Logs | `git` or `cm` on `PATH`, plus `gource` to play the visualization | -| Draft a changelog from history | Changelog | A Git or Plastic SCM checkout and an OpenAI API key for AI drafts | - -Review the repository content selected for an AI draft before sending it. -The AI commands can send commit messages, status output, or diff content -to OpenAI. Review the generated text before you use it. - -## How work leaves the desktop - -```mermaid -flowchart LR - UI["Vite interface"] --> Rust["Tauri commands in Rust"] - Rust --> FTP["FTPS hosting"] - Rust --> VCS["Git or Plastic SCM"] - Rust --> Gource["Gource log and playback"] - Rust --> AI["OpenAI for selected AI commands"] -``` - -Start with [a test deployment](deploy.md) if you are delivering a web build. -Use the [development and release guide](development.md) to work on the -desktop app itself. diff --git a/mkdocs.yml b/mkdocs.yml index 65e26eb..7b594b0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,21 +26,8 @@ nav: - LISA: "!import https://github.com/Unity-Environmental-University/matt_lisa?branch=main" - XR Education: - How the tools work together: xr-education/index.md - - Summit: - - Summit: xr-education/summit/index.md - - Send your first event: xr-education/summit/first-event.md - - Connect a Unity game: xr-education/summit/unity.md - - Data and reporting reference: xr-education/summit/data.md - - Trailhead: - - Trailhead: xr-education/trailhead/index.md - - Replay a sample recording: xr-education/trailhead/first-replay.md - - Record from Unity: xr-education/trailhead/unity.md - - Recording and sync reference: xr-education/trailhead/recording.md + - Summit: "!import https://github.com/Unity-Environmental-University/Summit?branch=main&docs_dir=docs/portal/*" + - Trailhead: "!import https://github.com/Unity-Environmental-University/Trailhead?branch=main&docs_dir=docs/portal/*" - Waste Management: "!import https://github.com/Unity-Environmental-University/WasteManagement?branch=main" - - XR Tools: - - XR Tools: xr-education/xr-tools/index.md - - Deploy a test build: xr-education/xr-tools/deploy.md - - Develop and release XR Tools: xr-education/xr-tools/development.md - - XR Tools Updater Service: - - XR Tools Updater Service: xr-education/xr-tools-updater-service/index.md - - Check an updater release: xr-education/xr-tools-updater-service/verify.md + - XR Tools: "!import https://github.com/Unity-Environmental-University/XR-Tools?branch=main&docs_dir=docs/portal/*" + - XR Tools Updater Service: "!import https://github.com/Unity-Environmental-University/XR-Tools-Updater-Service?branch=main&docs_dir=docs/portal/*" diff --git a/scripts/sync-xr-docs.py b/scripts/sync-xr-docs.py deleted file mode 100644 index f4ef246..0000000 --- a/scripts/sync-xr-docs.py +++ /dev/null @@ -1,57 +0,0 @@ -"""Refresh the public portal copies of explicitly listed private XR pages.""" - -import json -import subprocess -import tempfile -from pathlib import Path - - -ORGANIZATION = "Unity-Environmental-University" -PORTAL = Path(__file__).resolve().parents[1] -XR_DOCS = PORTAL / "docs" / "xr-education" - -# Keep these lists and the XR Education navigation in mkdocs.yml in sync. -# Files outside this list never enter the public export. -EXPORTS = { - "Summit": ("summit", ("index.md", "first-event.md", "unity.md", "data.md")), - "Trailhead": ("trailhead", ("index.md", "first-replay.md", "unity.md", "recording.md")), - "XR-Tools": ("xr-tools", ("index.md", "deploy.md", "development.md")), - "XR-Tools-Updater-Service": ("xr-tools-updater-service", ("index.md", "verify.md")), -} - - -def main(): - pages = {} - revisions = {} - with tempfile.TemporaryDirectory(prefix="xr-docs-") as temp_dir: - for repo, (section, filenames) in EXPORTS.items(): - url = f"https://github.com/{ORGANIZATION}/{repo}.git" - checkout = Path(temp_dir) / repo - subprocess.run( - [ - "git", "clone", "--quiet", "--depth=1", "--branch=main", - "--filter=blob:none", "--no-checkout", url, checkout, - ], - check=True, - ) - commit = subprocess.check_output( - ["git", "-C", checkout, "rev-parse", "HEAD"], text=True - ).strip() - revisions[f"{ORGANIZATION}/{repo}"] = commit - - for filename in filenames: - pages[XR_DOCS / section / filename] = subprocess.check_output( - ["git", "-C", checkout, "show", f"{commit}:docs/portal/{filename}"] - ) - - # A failed clone or missing page leaves the checked-in export intact. - for destination, content in pages.items(): - destination.parent.mkdir(parents=True, exist_ok=True) - destination.write_bytes(content) - (PORTAL / "xr-education-sources.json").write_text( - json.dumps(revisions, indent=2) + "\n", encoding="utf-8" - ) - - -if __name__ == "__main__": - main() diff --git a/xr-education-sources.json b/xr-education-sources.json deleted file mode 100644 index d0cd30a..0000000 --- a/xr-education-sources.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "Unity-Environmental-University/Summit": "c5f6b09816b10c2c053d2419dd794a05e641db26", - "Unity-Environmental-University/Trailhead": "11697155050f21b422b7cc1d7bf9a9a93e201b05", - "Unity-Environmental-University/XR-Tools": "1ee09c7b2848b4f851a12595a0d2a60eb566db20", - "Unity-Environmental-University/XR-Tools-Updater-Service": "85625d14947b67d303774546563173e9c7fa2287" -}