Build Workflow

Build & Publish Workflow

How to rebuild and publish the whole site, for whoever is operating this project end to end. For one language's translation workflow, see Translator Workflow instead. For any individual script's exact command syntax and flags, see Script Reference. This page is about the order scripts run in and how they compose, not their full option list.

The scripts, in the order you'd run them

1. Sync the end-user docs source from upstream

./pull_upstream_docs.sh

Upstream is the source of truth for the English end-user docs, not a locally-maintained copy: this syncs content/en/chapters/ and content/en/images/ from the official phpbb/documentation repo, overwriting local changes. Only en is affected; every other language's content/<lang>/ is generated from PO catalogs instead (see Translator Workflow), not synced from upstream directly.

Run this before step 2 so the build reflects current upstream content. proteus_doc_<lang>.xml's <bookinfo> is hand-maintained separately, not synced by this script.

2. Build the end-user docs

./phpbbdocs_hugo.sh all

Transforms every proteus_doc_<lang>.xml into Hugo Markdown, copies images, then runs hugo. This is the step that actually invokes hugo; none of the other scripts below do.

One line covers every language here, unlike step 3 below, because content/<lang>/chapters/*.xml (this step's source) is a committed, tracked file: a git pull already brings it up to date for whatever's translated so far, so there's nothing to regenerate per language first. site/content/<lang>/development/ (step 3's target) is the opposite: entirely gitignored, never committed, so it exists only once devdocs-build actually runs for that language.

3. Build the developer docs, per language

./translations.sh devdocs-build en site/content/en/development
./translations.sh devdocs-build da site/content/da/development
./translations.sh devdocs-build fr site/content/fr/development
./translations.sh devdocs-build de_x_sie site/content/de_x_sie/development
./translations.sh devdocs-build de site/content/de/development
./translations.sh devdocs-build it site/content/it/development

Reconstructs translated dev-docs Markdown for one language at a time, directly into the site content tree. Each devdocs-build assumes that language's PO catalogs already exist and are up to date: run ./translations.sh devdocs-check <lang> first if unsure. Doesn't run hugo itself; follow with step 2 again to fold the result into a real build.

4. Fill translation gaps with source-language fallbacks

./fill_translation_fallbacks.sh en da fr de_x_sie de it

For every page one language has that another doesn't, copies the source page over verbatim, flagged fallback: true, so the language switcher still links to something rather than nothing. Run this last, after whichever of steps 2–3 you just ran. It only fills gaps in whatever's already on disk.

Common workflows

Full site, all languages, from scratch:

./pull_upstream_docs.sh                  # syncs content/en/ from upstream
./phpbbdocs_hugo.sh all
./translations.sh devdocs-build en site/content/en/development
./translations.sh devdocs-build da site/content/da/development
./translations.sh devdocs-build fr site/content/fr/development
./translations.sh devdocs-build de_x_sie site/content/de_x_sie/development
./translations.sh devdocs-build de site/content/de/development
./translations.sh devdocs-build it site/content/it/development
./fill_translation_fallbacks.sh en da fr de_x_sie de it
./phpbbdocs_hugo.sh all                  # rebuild once more so the fallback/dev-docs pages are in the built site

Just want the latest end-user docs content?

./pull_upstream_docs.sh && ./phpbbdocs_hugo.sh all

The sync pulls current upstream chapters/images into content/en/, then the build picks them up. Follow with ./fill_translation_fallbacks.sh en da fr de_x_sie de it && ./phpbbdocs_hugo.sh all if the sync introduced pages a translation doesn't have yet.

Just want the latest developer docs?

./translations.sh devdocs-build en site/content/en/development

(and the same per other language you want refreshed) followed by ./phpbbdocs_hugo.sh all to fold it into a real build. A fresh English upstream pull doesn't automatically update translated catalogs; that's ./translations.sh devdocs-update <lang>, a separate step.

Adding a new language

That's a translator task, not a rebuild task: see Translator Workflow for the full walkthrough (both content families, from init/devdocs-init through to a committed PR).