# @algorandfoundation/algo-docs-sync

End-to-end documentation tooling for AlgoKit projects. Install once, pick the documentation generator you need, and every build copies your guides, invokes the configured generator (TypeDoc today, more stacks tomorrow), writes `manifest.json`, and publishes the result to a dedicated docs branch.

---

## 1. Install & authenticate

1. Add the tool as a dev dependency:
   ```bash
   npm install --save-dev @algorandfoundation/algo-docs-sync
   ```

---

## 2. Scaffold the repo

Run the initializer from your project root and **choose a generator** (required). For TypeScript repos you’ll typically pass `typedoc`; future generators (e.g., Python/Sphinx) will expose their own templates.

```bash
npx algo-docs init --generator typedoc
```

This command:

- Drops `docs-config.json` (guide + API glob rules plus a required `generator` field) and `typedoc.json` when using the `typedoc` generator.
- Copies `.github/workflows/build-docs.yml`, pre-wired with installation, build, manifest, and deploy steps.
- Creates a `docs/` folder if it doesn’t exist so you can start committing guide markdown right away.

Commit the generated files (`docs-config.json`, `typedoc.json`, `.github/workflows/build-docs.yml`) before moving on.

---

## 3. What the pipeline does

`docs-config.json` declares a `generator` and a `basePath`. Every run of `npx algo-docs build` dispatches to the selected generator. For the `typedoc` generator the flow is:

1. **Build** – run TypeDoc (with `typedoc-plugin-markdown`) to generate API docs at `basePath/api`.
2. **Stage** – `npx algo-docs stage` reads from `basePath/guides` and `basePath/api`, applies include/exclude filters, and copies the results to `docs-publish/<version>`.
3. **Manifest** – `npx algo-docs manifest` writes `basePath/manifest.json` including repo metadata, git info, and tool versions.
4. **Publish** – the workflow clones the current `docs-dist` branch into `docs-publish`, stages the filtered docs, and pushes the whole tree back via `peaceiris/actions-gh-pages`.
   - Manual dispatches refresh only `docs-dist/latest`.
   - Release events drop the new build into `docs-dist/v<tag>` (e.g., `docs-dist/v1.3.5`) **and** also refresh `docs-dist/latest` so you always have a rolling view and versioned snapshots.

Developers can explore the generated docs locally by opening the `basePath/` directory, while CI keeps the branch copy in sync.

---

## 4. Wire up GitHub Actions

The initializer drops the `build-docs.yml` workflow into the `.github.workflows/` folder.

Key secrets:

- `GITHUB_TOKEN` (provided automatically) – used by `peaceiris/actions-gh-pages` to push to `docs-dist`. Ensure the repo’s Workflow permissions allow write access.

Once merged into your default branch, the workflow will:

- Update `docs-dist/latest` on pushes, pull requests, and manual dispatches.
- Create `docs-dist/<release-tag>` when you publish a GitHub Release.

You can download the generated artifact (`docs-dist.zip`) from each run if you need to inspect the raw files.

---

## 5. Local commands

- `npx algo-docs validate` – schema-check `docs-config.json`.
- `npx algo-docs build` – run TypeDoc to generate API docs at `basePath/api`. Pass `--generator <name>` to override the `generator` value declared in `docs-config.json`.
- `npx algo-docs stage` – copy and filter docs from `basePath/guides` and `basePath/api` to `docs-publish/<version>`. Use `--version <tag>` for versioned releases and `--update-latest` to also update the latest folder.
- `npx algo-docs manifest` – write `basePath/manifest.json` with repo metadata, git info, and tool versions.
- `npx algo-docs migrate` – update an existing `docs-config.json` to the latest schema version.

These commands respect `--config`, `--verbose`, and `--quiet` flags so you can customize paths or diagnostics when experimenting locally.

---

## 7. Generators

The CLI ships with a pluggable generator system:

| Name     | Description                                                      |
| -------- | ---------------------------------------------------------------- |
| `typedoc` | Builds API markdown from TypeScript entry points using TypeDoc and `typedoc-plugin-markdown`. |

Set the generator in `docs-config.json` (e.g., `"generator": "typedoc"`) or via `--generator` on the CLI. Additional stacks (Python/Sphinx, Rust/mdBook, etc.) can plug in without changing the shared workflow—just ship a new generator package and register it.

---

## 6. Where your docs live

| Location                    | When it updates                              | What it contains                                                                                                                            |
| --------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `basePath/` (workspace)     | After `npx algo-docs build` locally or in CI | Working copy of guides (at `basePath/guides`) and API markdown (at `basePath/api`). Safe to inspect or serve locally.                       |
| `docs-publish/` (workspace) | After `npx algo-docs stage`                  | Filtered docs ready for publishing. Contains versioned folders (e.g., `latest`, `v1.2.0`).                                                  |
| `docs-dist/latest` (branch) | Manual dispatches and releases               | Rolling view of the most recently published docs. Release runs refresh this folder in addition to their versioned snapshot.                 |
| `docs-dist/<tag>` (branch)  | GitHub Release published                     | Immutable snapshot of the docs that correspond to that package version (e.g., `v2.5.0`). Useful for historic doc sets or version switchers. |

Publish targets can be adjusted by editing `.github/workflows/build-docs.yml`, but the defaults above cover most repos: "latest" for ongoing work, and "vX.Y.Z" for tagged releases.