docs: refactor and expand docs by polyipseity · Pull Request #47 · USThing/template-api

polyipseity · 2026-01-18T10:06:12Z

Apart from adding docs, this adds a workflow to publish "./docs/api" as GH pages. Might need to set it up.

Fixes #52.

polyipseity · 2026-01-24T09:19:59Z

Fixes #52.

FlandiaYingman · 2026-01-26T07:58:53Z

Wow, is it done? I will take a look at it later.

Copilot

Pull request overview

This PR refactors and expands the repository’s human-authored documentation and adds TypeDoc generation/publishing so ./docs/api can be published as GitHub Pages.

Changes:

Add new docs/ guides (quickstart, CI, env vars, routes/plugins overviews, deployment, release notes, testing/linting).
Add TypeDoc configuration + scripts, and ignore generated output (docs/api) in git.
Add GitHub Actions workflows to build docs and publish generated TypeDoc output.

Reviewed changes

Copilot reviewed 19 out of 21 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
`yarn.lock`	Adds TypeDoc and its transitive dependencies to the lockfile.
`typedoc.json`	TypeDoc configuration targeting `src/` and outputting to `docs/api`.
`src/routes/README.md`	Removes old routes folder README in favor of centralized docs under `docs/`.
`src/plugins/README.md`	Removes old plugins folder README in favor of centralized docs under `docs/`.
`scripts/clean-docs.js`	Adds a helper script to remove generated TypeDoc output directory.
`package.json`	Adds `docs:typedoc` / `docs:clean` scripts and `typedoc` devDependency.
`docs/testing-and-linting.md`	New guide for running tests and linting locally.
`docs/routes.md`	New overview of route loading/structure and where generated docs live.
`docs/release.md`	New summary of release automation workflow behavior.
`docs/quickstart.md`	New expanded quickstart guide for local setup and usage.
`docs/plugins.md`	New overview of plugin loading and key plugins provided.
`docs/env-vars.md`	New environment variable guide and conventions (incl. `.env*` ignore).
`docs/docker-and-deployment.md`	New Docker build/run and CI publishing guide.
`docs/dev-setup.md`	New developer setup guide focusing on Corepack/Yarn.
`docs/ci.md`	New overview of CI workflows and hosted/self-hosted fallback behavior.
`README.md`	Refactors README to link to docs/scripts and describe docs generation.
`CONTRIBUTING.md`	Improves wording/formatting for contribution guidelines.
`.gitignore`	Ignores generated TypeDoc output under `docs/api/`.
`.github/workflows/docs.yml`	New workflow to generate TypeDoc and upload it as an artifact on PR/push.
`.github/workflows/docs-publish.yml`	New workflow intended to publish `docs/api` output to GitHub Pages on `main`.
`.env.example`	Expands env example with auth skip/runtime/test helper variables.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

.github/workflows/docs-publish.yml

.github/workflows/docs.yml

README.md

.env.example

docs/quickstart.md

.github/workflows/docs-publish.yml

.github/workflows/docs.yml

Details will be moved under `docs/`.

…llback (PR #48)

…nd runner defaults

… docker metadata, release-please behavior

…gnore, workflows

…te README and .gitignore

… cache for docs workflows Use numeric node-version (24) in `.github/workflows/docs.yml` and `.github/workflows/docs-publish.yml` Enable Corepack and run `corepack install` before installing dependencies Split node/cache setup to a dedicated `setup-node` step with `cache: yarn` Reorder and consolidate dependency install steps (Corepack prepare + yarn install --frozen-lockfile) Minor comment formatting fix in `docs-publish.yml`

Grant pages write permission; use yarn install --immutable --immutable-cache instead of corepack prep.

Update README docs-site badge to GitHub Pages URL and minor docs wording fixes. Remove UTF-8 BOM from `.env.example`.

…dling

Copilot

Pull request overview

Copilot reviewed 19 out of 21 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

README.md

.github/workflows/docs.yml

.github/workflows/docs-publish.yml

.github/workflows/docs.yml

.github/workflows/docs-publish.yml

FlandiaYingman · 2026-02-19T05:29:21Z

You might also want to fix the runner selection for this repo.

Copilot

Pull request overview

Copilot reviewed 19 out of 21 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-19T05:38:04Z

docs/ci.md

+
+## Key notes
+
+- Hosted-first fallback: jobs use a small probe job (`detect-quota`) and set `runs-on` dynamically so CI prefers `ubuntu-latest` but can fall back to `self-hosted` when needed.


The documentation states that CI jobs prefer ubuntu-latest, but the actual workflow files (check.yml, docs.yml, docs-publish.yml) use ubuntu-slim as the hosted runner label. Update this line to reference ubuntu-slim to match the actual implementation.

Suggested change

- Hosted-first fallback: jobs use a small probe job (`detect-quota`) and set `runs-on` dynamically so CI prefers `ubuntu-latest` but can fall back to `self-hosted` when needed.

- Hosted-first fallback: jobs use a small probe job (`detect-quota`) and set `runs-on` dynamically so CI prefers `ubuntu-slim` but can fall back to `self-hosted` when needed.

Copilot · 2026-02-19T05:38:04Z

.github/workflows/docs.yml

+name: docs
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+


Consider adding concurrency control to this workflow (similar to check.yml and docker.yml) to avoid redundant doc builds when multiple commits are pushed to the same PR. This would save CI resources and reduce noise. Example:

concurrency: group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.sha }} cancel-in-progress: true

Copilot · 2026-02-19T05:38:04Z

docs/release.md

+Releases are produced by `googleapis/release-please-action`. The release workflow has been refactored so release steps are defined in `.github/workflows/release-shared-steps.yml` and invoked by a small top-level caller (`.github/workflows/release.yml`) which prefers hosted runners and falls back to `self-hosted` when the top-level try job fails.
+
+- Trigger: push to `main`.
+- Behavior: `googleapis/release-please-action` parses Conventional Commits and will open/update Release PRs or create a release when appropriate; it also generates/updates the changelog (`CHANGELOG.md`) and exposes outputs such as `release_created`, `major`, `minor`, `patch`, `tag_name`, and `body`.
+- CI integration: the shared-step workflow consumes those outputs to tag versions and to build/push container images (see the repository workflows for exact steps). The hosted-first / self-hosted fallback may cause duplicate PR checks to appear when the fallback runs — this is cosmetic.


The documentation describes a "shared-step workflow" (release-shared-steps.yml) and a "top-level caller", but the release workflow is actually defined entirely in .github/workflows/release.yml with no separate shared-steps file. Update this section to accurately describe the single release.yml workflow that contains all release steps inline.

Suggested change

Releases are produced by `googleapis/release-please-action`. The release workflow has been refactored so release steps are defined in `.github/workflows/release-shared-steps.yml` and invoked by a small top-level caller (`.github/workflows/release.yml`) which prefers hosted runners and falls back to `self-hosted` when the top-level try job fails.

- Trigger: push to `main`.

- Behavior: `googleapis/release-please-action` parses Conventional Commits and will open/update Release PRs or create a release when appropriate; it also generates/updates the changelog (`CHANGELOG.md`) and exposes outputs such as `release_created`, `major`, `minor`, `patch`, `tag_name`, and `body`.

- CI integration: the shared-step workflow consumes those outputs to tag versions and to build/push container images (see the repository workflows for exact steps). The hosted-first / self-hosted fallback may cause duplicate PR checks to appear when the fallback runs — this is cosmetic.

Releases are produced by `googleapis/release-please-action`, via a single workflow defined in `.github/workflows/release.yml`. This workflow prefers hosted runners and falls back to `self-hosted` when the top-level try job fails.

- Trigger: push to `main`.

- Behavior: `googleapis/release-please-action` parses Conventional Commits and will open/update Release PRs or create a release when appropriate; it also generates/updates the changelog (`CHANGELOG.md`) and exposes outputs such as `release_created`, `major`, `minor`, `patch`, `tag_name`, and `body`.

- CI integration: the `release.yml` workflow consumes those outputs to tag versions and to build/push container images (see the repository workflows for exact steps). The hosted-first / self-hosted fallback may cause duplicate PR checks to appear when the fallback runs — this is cosmetic.

Copilot · 2026-02-19T05:38:05Z

docs/docker-and-deployment.md

+A `Dockerfile` exists at the repository root. CI image build/publish logic has been extracted into an internal shared-step workflow (`.github/workflows/docker-shared-steps.yml`) and is invoked by a small top-level caller (`.github/workflows/docker.yml`) that prefers hosted runners and falls back to `self-hosted` when the hosted job fails.
+
+## Local build & run
+
+Build the image locally (from repo root):
+
+```bash
+# build
+docker build -t template-api:local .
+
+# run (expose port 3000)
+docker run --rm -p 3000:3000 --env-file .env.example template-api:local
+```
+
+Replace `--env-file .env.example` with your `.env` file or explicit `-e` flags for required environment variables.
+
+## CI image publishing
+
+The repository's `docker.yml` top-level caller invokes the internal shared-step workflow to build and push images to the registry. The shared-step workflow:
+
+- sets up QEMU and Buildx
+- logs into the registry using the workflow token
+- generates metadata tags (sha, branch/ref, test)
+- builds and pushes the image(s)
+
+If you need to change the target registry or image name, update the `REGISTRY` and `IMAGE_NAME` environment variables in the shared-step workflow or the top-level caller as appropriate.


The documentation describes a "shared-step workflow" (docker-shared-steps.yml) and a "top-level caller", but the docker workflow is actually defined entirely in .github/workflows/docker.yml with no separate shared-steps file. Update this section to accurately describe the single docker.yml workflow that contains all build/push steps inline.

polyipseity self-assigned this Jan 18, 2026

polyipseity added the documentation Improvements or additions to documentation label Jan 18, 2026

polyipseity force-pushed the add-docs branch 4 times, most recently from dc4c0cf to 21fa8ee Compare January 24, 2026 08:55

polyipseity mentioned this pull request Jan 24, 2026

Internal docs for template API #52

Open

polyipseity force-pushed the add-docs branch from fe0b9ed to f4c72f0 Compare January 25, 2026 05:26

polyipseity marked this pull request as ready for review January 25, 2026 05:28

polyipseity force-pushed the add-docs branch from 34eeaa8 to 615ba34 Compare January 25, 2026 06:46

FlandiaYingman requested a review from Copilot February 7, 2026 06:39

Copilot started reviewing on behalf of FlandiaYingman February 7, 2026 06:39 View session

Copilot AI reviewed Feb 7, 2026

View reviewed changes

polyipseity added 15 commits February 17, 2026 20:12

docs: update readme to be more concise

952dd62

Details will be moved under `docs/`.

docs: add quickstart and development setup

47fcaf8

docs: migrate and add plugins and routes docs

8f4fe3e

docs: deduplicate docs

7cdf722

docs: add testing, linting, and CI

94591bb

docs: add Docker and deployment

5c07603

docs: fix typo

a27f04e

docs: improve .env.example and add env var docs

6d20041

docs: document .env ignore policy in env-vars.md

c1008bb

docs: format CONTRIBUTING.md

b783da7

docs: edit CONTRIBUTING.md for wording

e222955

docs: add release automation docs

a7dfa36

docs(ci): document reusable workflows and hosted-first self-hosted fa…

9b49300

…llback (PR #48)

docs(ci): update workflow docs for shared-step try→fallback pattern a…

12fe36e

…nd runner defaults

docs(ci): update workflow docs - detect-quota, hosted-first fallback,…

d0bf1f3

… docker metadata, release-please behavior

polyipseity added 6 commits February 17, 2026 20:13

docs(ci): add TypeDoc generation and publishing; update README, .giti…

762f5f7

…gnore, workflows

docs(ci): add docs-publish workflow; generate & publish TypeDoc; upda…

a4efb72

…te README and .gitignore

docs: add script docs (compile, lint:check, fmt) and fix lint command

882cf88

ci: update docs publish workflow

b693501

Grant pages write permission; use yarn install --immutable --immutable-cache instead of corepack prep.

docs: fix docs links

9abe148

Update README docs-site badge to GitHub Pages URL and minor docs wording fixes. Remove UTF-8 BOM from `.env.example`.

polyipseity force-pushed the add-docs branch from 615ba34 to 9abe148 Compare February 17, 2026 12:33

polyipseity added 3 commits February 17, 2026 20:34

ci: fix

223a575

docs: sync documentation with code — clarify test runner and .env han…

3424062

…dling

chore: format

96ad1c2

FlandiaYingman requested a review from Copilot February 18, 2026 08:20

Copilot started reviewing on behalf of FlandiaYingman February 18, 2026 08:20 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

polyipseity added 2 commits February 19, 2026 12:39

ci: bump action versions

04ef9dc

docs: fix readme

bf5f157

FlandiaYingman requested a review from Copilot February 19, 2026 05:28

Copilot started reviewing on behalf of FlandiaYingman February 19, 2026 05:29 View session

Copilot AI reviewed Feb 19, 2026

View reviewed changes


		## Key notes

		- Hosted-first fallback: jobs use a small probe job (`detect-quota`) and set `runs-on` dynamically so CI prefers `ubuntu-latest` but can fall back to `self-hosted` when needed.

Conversation

polyipseity commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

polyipseity commented Jan 24, 2026

Uh oh!

FlandiaYingman commented Jan 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

FlandiaYingman commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

polyipseity commented Jan 18, 2026 •

edited

Loading