Documentation #67
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Build the wodoc documentation (manual + API) with odoc, theme it with the | |
| # Ocsigen chrome using wodoc ITSELF (dogfooding), and publish it on the project's | |
| # gh-pages branch, served at https://ocsigen.org/wodoc/. See doc/README.md. | |
| # | |
| # - push to master -> rebuild and deploy the "dev" docs. | |
| # - manual dispatch -> build any version (e.g. a release tag) and optionally make | |
| # it the "latest". | |
| # | |
| # Historical version directories already on gh-pages are PRESERVED: each run only | |
| # replaces its own <label>/ directory (deploy clean is scoped to the target folder). | |
| name: Documentation | |
| on: | |
| push: | |
| branches: [master] | |
| workflow_dispatch: | |
| inputs: | |
| label: | |
| description: "Version label / output directory (e.g. dev, 0.1.0)" | |
| required: true | |
| default: dev | |
| ref: | |
| description: "Git ref to build (branch or tag). Defaults to the label." | |
| required: false | |
| default: "" | |
| set_latest: | |
| description: "Also repoint 'latest' at this build" | |
| type: boolean | |
| default: false | |
| # Don't run on forks: deployment targets ocsigen/wodoc's gh-pages. | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} | |
| cancel-in-progress: ${{ github.event_name == 'pull_request' }} | |
| jobs: | |
| build-deploy: | |
| if: github.repository == 'ocsigen/wodoc' | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| env: | |
| LABEL: ${{ github.event.inputs.label || 'dev' }} | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| with: | |
| ref: ${{ github.event.inputs.ref || github.event.inputs.label || github.sha }} | |
| fetch-depth: 0 | |
| - name: Set up OCaml | |
| uses: ocaml/setup-ocaml@v3 | |
| with: | |
| ocaml-compiler: "5.4.0" | |
| # The bottleneck of this job is compiling the dependency tree plus odoc from | |
| # source; setup-ocaml only caches the base switch (the compiler), so they | |
| # recompiled on every push. Cache the whole _opam switch keyed on wodoc.opam | |
| # (the dep set); on a cache hit the install is skipped and only the wodoc | |
| # binary itself is rebuilt from this checkout (dune, below). The key changes | |
| # — and the deps/odoc rebuild once — only when wodoc.opam changes. wodoc is | |
| # not opam-installed (it is built via dune and run from _build), so it never | |
| # lands in the cached switch. | |
| - name: Cache the opam switch (deps + odoc) | |
| id: switch-cache | |
| uses: actions/cache@v4 | |
| with: | |
| path: _opam | |
| key: opam-switch-${{ runner.os }}-ocaml5.4.0-${{ hashFiles('*.opam') }} | |
| - name: Install dependencies | |
| if: steps.switch-cache.outputs.cache-hit != 'true' | |
| run: | | |
| opam install . --deps-only --with-doc | |
| # odoc: the documentation backend wodoc drives. | |
| opam install odoc | |
| # No wodoc pin: we build wodoc from this checkout and theme its own | |
| # documentation with it (dogfooding the turn-key `wodoc build`). | |
| - name: Build documentation | |
| # Dogfood: build the wodoc binary from this checkout, then run its | |
| # turn-key build on wodoc's own doc/wodoc config. `wodoc build` runs | |
| # `dune build @doc` itself and assembles every page with the shared | |
| # Ocsigen chrome, fetched from the single canonical menu served by | |
| # ocsigen.org, into _doc-site/<label>/. | |
| run: | | |
| opam exec -- dune build bin/main.exe | |
| opam exec -- _build/default/bin/main.exe build \ | |
| --config doc/wodoc --out "_doc-site/$LABEL" \ | |
| --menu https://ocsigen.org/doc/menu.html --label "$LABEL" | |
| - name: Deploy to gh-pages (replace only this version, keep the rest) | |
| uses: JamesIves/github-pages-deploy-action@v4 | |
| with: | |
| branch: gh-pages | |
| folder: _doc-site/${{ env.LABEL }} | |
| target-folder: ${{ env.LABEL }} | |
| clean: true | |
| # GitHub Pages must NOT run Jekyll: the Markdown twins contain {%wodoc:%} | |
| # examples that Jekyll's Liquid parser rejects. A .nojekyll at the site root | |
| # disables it. (clean above is scoped to <label>/, so this persists.) | |
| - name: Disable Jekyll (.nojekyll at the site root) | |
| run: mkdir -p _ghroot && touch _ghroot/.nojekyll | |
| - uses: JamesIves/github-pages-deploy-action@v4 | |
| with: | |
| branch: gh-pages | |
| folder: _ghroot | |
| target-folder: . | |
| clean: false | |
| - name: Repoint 'latest' (releases) | |
| if: ${{ github.event.inputs.set_latest == 'true' }} | |
| run: | | |
| tmp="$(mktemp -d)" | |
| git clone --depth 1 --branch gh-pages \ | |
| "https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git" "$tmp" | |
| ln -sfn "$LABEL" "$tmp/latest" | |
| git -C "$tmp" add latest | |
| git -C "$tmp" -c user.email=ci@ocsigen.org -c user.name="Ocsigen CI" \ | |
| commit -m "doc: latest -> $LABEL" || true | |
| git -C "$tmp" push |