Chuyển tới nội dung chính

Documentation standard

This site is the only ProjectV SDK documentation. It replaced the V1 ProjectZ-CrossSDK site and the earlier V3 draft; do not start a second one.

Layout​

PathContent
website/docs/intro.mdLanding page and audience split
website/docs/client/Client Guide: overview → setup → concepts → scenes → screen contracts → presenters → recipes → errors → recovery → lifecycle → migration → troubleshooting → checklist
website/docs/client/presenters/One page per public presenter (with its screen contract, when it has one), plus shared types
website/docs/sdk-team/Maintainer pages (this track)
website/scripts/validate-client-docs.jsValidator run before every build

English only. Use explicit heading IDs (## Title {#id}) so links stay stable.

Client Guide rules​

  • Start from a real Client task (login, render Lobby, purchase, begin a mission, settle, logout), not from an API dump.
  • Use only public IProjectV*Screen and IProjectV*Presenter contracts, their views and snapshots, and the documented helpers. Never show IProjectVSdk, feature clients, adapters, Nakama types, raw RPC or runtime composition in Client pages.
  • Show cancellation and disposal in lifecycle examples, and the failure path, not only success.
  • Keep server-authoritative values opaque; never compute them in examples.
  • Prefer code that exists in ProjectV-Client or the SDK tests.

Presenter reference rules​

Each presenter page has: one-sentence purpose, a Screen contract section when the feature has one, Snapshot table, Methods table, one Example, and Notes. Examples use the screen contract when there is one. A change to a public presenter or screen contract updates its page in the same pull request.

Validation​

npm run build runs scripts/validate-client-docs.js first. It fails when:

  • a Client page is missing, or has a duplicate heading ID;
  • a Client page mentions a forbidden internal type (IProjectVSdk, ProjectVFeatureClients, ProjectVNakamaCapabilityClients, Nakama clients, .client.nakama);
  • a Client page names an IProjectV* / ProjectV* type that does not exist in packages/ (so docs cannot reference a removed or misspelt API).

Docusaurus then fails on broken internal links (onBrokenLinks: 'throw').

Build and publish​

cd website
npm ci
npm start          # http://localhost:3000
npm run build      # validator + static site in website/build

.github/workflows/deploy-docs.yml builds and publishes to GitHub Pages on every push to v3 that touches website/** (or a manual run). The repository setting Pages → Build and deployment → Source must be GitHub Actions. website/Dockerfile and compose.yml serve the same build with nginx for a self-hosted copy.

References​