blob: 7e80f3f7cb44711389c615814ef217d0f45d7f03 [file] [view]
# build-docs.py
Builds the complete Juneau documentation site locally: Maven site and javadocs from a Juneau checkout, then the Docusaurus build, then the integrity and link checks.
## When to use
- You want to build the full site exactly as the publish pipeline does, before staging it.
- You only need the Docusaurus smoke build with no Juneau checkout: use `--skip-maven`.
- You are editing pages and want live preview: use `start-docusaurus.py`; it does not build the site.
- To publish what you built, use `release-docs-stage.py` and then `release-docs.py`.
## Usage
```bash
python3 scripts/build-docs.py
python3 scripts/build-docs.py --staging --juneau-root ~/git/apache/juneau
python3 scripts/build-docs.py --skip-maven --skip-copy
python3 scripts/build-docs.py --dry-run
```
Run from the docs checkout root.
## Options
| Option | Argument | Default | Meaning |
|---|---|---|---|
| `--skip-npm` | none | off | Skip `npm ci` and the Docusaurus build. |
| `--skip-maven` | none | off | Skip `mvn clean install`, `mvn site`, the apidocs check, the javadoc and site copies, and (when the Juneau checkout is missing) the link checks. With a Juneau checkout present the link checks still run, since they read its sources, not Maven output. The Juneau checkout may be missing. |
| `--skip-copy` | none | off | Skip copying the Maven site into `static/site` and the `.asf.yaml` copy. The versioned javadocs copy still runs. |
| `--skip-verify` | none | off | Skip the documentation-integrity, project-page and entry-page checks (`verify-docs.py`, `check-project-pages.py`, `check-entry-pages.py`). |
| `--staging` | none | off | Build with `SITE_URL=https://juneau.staged.apache.org`. |
| `--dry-run` | none | off | Print every command and copy that would run; do no work. Output is plain, never the live view. |
| `--verbose` | none | off | Print the full banner for each stage instead of one line. |
| `--juneau-root` | directory | `$JUNEAU_ROOT`, then `../master`, then `../juneau` | Juneau source checkout to build against. Must contain `pom.xml`. |
| `--console` | `full`, `board`, `none` | `board` | Console output when the Juneau checkout provides `juneau-terminal`; also `JUNEAU_TERMINAL_CONSOLE` (the flag wins). |
## What it does
1. Resolves the Juneau checkout (`juneau_root.find_juneau_root`) and changes into the docs directory.
2. With a Juneau checkout that has `juneau-terminal`, each stage below is a row of its live view (Clean, npm, Install, Site, Copy, Docs build, Verify, Links); skipped stages show as skipped rows. Without it, or with `--dry-run`, output is plain.
3. **Clean:** checks that `node`, `npm`, `mvn` and `java` are on the path, then deletes `build/`.
4. **npm:** runs `npm ci`. It is skipped automatically when a Docusaurus dev server is detected (a `docusaurus start` process, something listening on port 3000, or a `.dev-server-running` file), because both would corrupt the shared webpack cache. The Docusaurus build is skipped for the same reason.
5. When the Juneau checkout exists (or `--skip-maven` is not set), reads the current release with the Juneau checkout's `scripts/current-release.py`, and regenerates `artifact-paths.json` from the module `pom.xml` files (it refuses to overwrite the file if no jar-packaged module is found).
6. **Install and Site:** runs `mvn clean install -DskipTests` and `mvn site -DskipTests` in the Juneau checkout, then checks that `target/site/apidocs` exists.
7. **Copy:** copies `target/site/apidocs` to `static/javadocs/<version>/` and adds or updates the entry in `static/javadocs/releases.json`; unless `--skip-copy`, replaces `static/site` with the Maven site.
8. Regenerates `artifact-packages.json` (module to base javadoc package), then points `static/site/apidocs` at the committed `static/javadocs/<version>` with a relative symlink.
9. **Docs build:** runs `npm run build`, setting `JUNEAU_VERSION` and, with `--staging`, `SITE_URL`.
10. Copies the Juneau checkout's `.asf.yaml` into `build/` (not with `--skip-copy` or `--skip-maven`).
11. **Verify:** runs `verify-docs.py` (Integrity), `check-project-pages.py` (Project pages) and `check-entry-pages.py` (Entry pages, with `--juneau-root` when the Juneau checkout has a `pom.xml`) and `check-doc-inventory.py` (Doc inventory), four child rows of the Verify stage.
12. **Links:** runs `check-topic-links.py --juneau-root <root>`, `check-ai-artifacts.py --juneau-root <root>`, `check-code-fences.py --docs-root <docs>`, `check-java-fences.py --docs-root <docs> --strict` (a ` ```java ` fence that does not parse fails the build unless it is marked ` ```java fragment `) and `check-guide-snippets.py --juneau-root <root>` (every ` guide=FILE#REGION ` fence must match its region in the Juneau checkout's `juneau-examples/juneau-examples-guides` module).
13. Prints the location of the build and, after a complete build with no skips, the stage and release commands.
## Output and exit codes
Progress is the `juneau-terminal` live view or plain stage banners; the finished site is in `build/`. Files written outside `build/`: `artifact-paths.json`, `artifact-packages.json` (both only when their content changed), `static/javadocs/<version>/`, `static/javadocs/releases.json`, `static/site/`.
| Code | Meaning |
|---|---|
| 0 | Build completed. |
| 1 | A prerequisite tool is missing, a command failed, the Maven site or apidocs were not produced, the Juneau checkout is invalid or missing, or the run was interrupted. |
## Gotchas
- Maven runs are serialized with the Juneau push and agent builds: the Install, Site and Copy stages hold the shared Maven lock (`mvn_lock.py`, the same `mkdir` lock directory as `~/agents/skills/juneau-worktrees/juneau-mvn-lock.sh`; `JUNEAU_MVN_LOCKDIR` overrides it), so a concurrent `push.py` in the Juneau checkout cannot clean `target/` mid-build. The wait is announced with the holder's pid and command, then about every minute. A killed build releases the lock. `--dry-run` and `--skip-maven` take no lock.
- It changes tracked files (`artifact-paths.json`, `artifact-packages.json`, `static/javadocs/`); check `git status` afterwards.
- A full build runs Maven over the whole Juneau tree and is slow; use the skip flags for iteration.
- The completion reminder is suppressed when `JUNEAU_PUSH_ACTIVE` is set and the live view is active.
- Warnings (missing `current-release.py`, missing javadocs directory) do not fail the build; the affected step is skipped.
## See also
- `verify-docs.py`, `check-project-pages.py`, `check-entry-pages.py`, `check-topic-links.py`, `check-ai-artifacts.py`, `check-code-fences.py`, `check-java-fences.py`, `check-guide-snippets.py`, `release-docs-stage.py`, `release-docs.py`, `start-docusaurus.py`
- Docs site: Developer Info, Script: build-docs (`pages/developer-info/04.03.03.ScriptBuildDocs.md`)