# How the Eliom documentation is generated

The Eliom documentation published at <https://ocsigen.org/eliom/> is built with
**odoc** and themed with the Ocsigen site chrome by
[**wodoc**](https://github.com/ocsigen/wodoc) (an odoc driver). The same odoc
sources are also what ocaml.org renders.

Eliom is a **client/server** project: it ships its server and client APIs as two
libraries of the same package (`eliom.server` / `eliom.client`) with the **same
module names**, so `dune build @doc` collides. The API is therefore built with
`odoc_driver eliom --remap` (the engine ocaml.org uses) on the **installed**
package — i.e. the documented version is whatever the build switch has installed.

## Sources

| What | Where | Format |
|---|---|---|
| Manual | the package's `(documentation)` `.mld` (built with the API by odoc_driver) | odoc pages |
| Manual nav order | `doc/manual/menu.wiki` (overlaid from the `wikidoc` branch by CI) | wiki menu |
| Server / client API | `doc/server.indexdoc` / `doc/client.indexdoc` (curated module index) | odoc index |
| API (`.mli`) | the installed `eliom` package | odoc comments |
| Site configuration | [`doc/wodoc`](wodoc) | wodoc config (S-expression) |

The whole site — per-side API navs, the client/server switch, the body colour,
the shared manual nav, and the rewriting of sibling Ocsigen projects' cross-refs
to relative links — is declared in [`doc/wodoc`](wodoc) and produced by a single
`wodoc build`. There is **no `build.sh`** and no Python.

## Build

`wodoc build` documents the **installed** `eliom`, so install it first (from the
ref you want to document) in a switch that also has `odoc_driver` and `wodoc`:

```
opam install ./eliom.opam            # the version to document
opam install wodoc                   # the odoc driver / theming
# overlay the manual menu (lives on the wikidoc branch):
git show origin/wikidoc:doc/dev/manual/menu.wiki > doc/manual/menu.wiki
wodoc build --config doc/wodoc --label dev --out _doc-site/dev \
  --menu https://ocsigen.org/doc/menu.html
```

`wodoc build` runs `odoc_driver eliom --remap` (after preprocessing the installed
manual `.mld`), assembles every page into the Ocsigen site and writes the version
redirect. Add `--local` to fetch the shared `/css//img/` assets and preview offline.

> **Prerequisite (CI).** Eliom's cross-library links need the `odoc_driver`
> `base_args` fix, which is not yet upstreamed. CI must pin `odoc` / `odoc-driver`
> from the patched source until that lands; see the workflow comments.

## Deployment (CI)

[`.github/workflows/doc.yml`](../.github/workflows/doc.yml) builds and publishes to
the project's **`gh-pages`** branch (served at `ocsigen.org/eliom/`). The CI
triggers **only on `master`**, so pushing any other branch never deploys:

- **push to `master`** → rebuilds and deploys the **`dev`** docs only.

Stable versions are **not** built by CI: they are generated by hand and committed
to `gh-pages` (with the `latest` symlink repointed) at release time. Each CI run
replaces only the `dev/` directory; the other version directories already on
`gh-pages` are preserved.

## Releasing a stable version

The CI builds only `dev/`. To publish a stable version, trigger the
**Documentation** workflow's `release` job with the **version** input — either:

- **CLI** (from a clone of the repo): `gh workflow run doc.yml -f version=1.2.3`
- **GitHub UI**: repo → *Actions* → *Documentation* (left sidebar) → *Run workflow*
  (top-right) → set **version** (e.g. `1.2.3`) → *Run workflow*.

The `release` job freezes the current `dev/` docs as `/<version>/`, repoints the
`latest` symlink, writes the root redirect and refreshes `versions.json` — via
`wodoc release --from dev --version <version>`. No rebuild: the docs of a release
are exactly the `dev` docs at that point.

Equivalently, by hand on a `gh-pages` checkout:

```
wodoc release --site . --from dev --version <version>
git add -A && git commit -m "Release doc <version>" && git push
```
