This is an automated email from the ASF dual-hosted git repository.
hansva pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/main by this push:
new b49918e17b Document how to build and preview the manuals locally.
#2605 (#8905)
b49918e17b is described below
commit b49918e17bb9d1ac2fe2bc855fe7c45fb3e8cf46
Author: Adalennis <[email protected]>
AuthorDate: Wed Oct 14 14:05:19 2026 +0200
Document how to build and preview the manuals locally. #2605 (#8905)
* Document how to build and preview the manuals locally. #2605
* Use run-website-local.sh to preview the manuals locally. #2605
---
.../modules/ROOT/pages/writing-documentation.adoc | 31 +++++++++++++++++++++-
1 file changed, 30 insertions(+), 1 deletion(-)
diff --git a/docs/hop-dev-manual/modules/ROOT/pages/writing-documentation.adoc
b/docs/hop-dev-manual/modules/ROOT/pages/writing-documentation.adoc
index 3caaf79ed3..262193fd9b 100644
--- a/docs/hop-dev-manual/modules/ROOT/pages/writing-documentation.adoc
+++ b/docs/hop-dev-manual/modules/ROOT/pages/writing-documentation.adoc
@@ -20,6 +20,7 @@ under the License.
Documentation lives in the Hop repository next to the code it describes, in
`docs/`.
Changing it is an ordinary pull request, which makes it one of the easiest
ways to make a first contribution.
+The
https://hop.apache.org/community/contribution-guides/documentation-contribution-guide/[Documentation
Contribution Guide] on the website walks through forking the repository and
opening that pull request.
== The three manuals
@@ -64,11 +65,39 @@ The path is relative to the user manual on the website, and
it is what the help
Anything a plugin developer needs — rather than a user — belongs in this
manual instead.
+== Previewing the documentation locally
+
+The manuals are published by the Antora playbooks in the
https://github.com/apache/hop-website[apache/hop-website] repository, not this
one.
+Its `run-website-local.sh` script builds the website with the documentation
from your Hop checkout and serves it.
+
+. Install Node.js 22, the version the pull request build uses.
+. Check out apache/hop-website next to your Hop checkout.
+The build reads `../hop`, so the Hop checkout has to be in a folder named
`hop`:
++
+----
+work/
+├── hop/ your Hop checkout, on the branch you want to preview
+└── hop-website/ a checkout of apache/hop-website, on main
+----
+. In `hop-website`, run the script:
++
+[source,bash]
+----
+./run-website-local.sh
+----
++
+It reads the working tree of `../hop`, so uncommitted edits are included.
+When the server is up, the manuals are at
`+http://localhost:4000/manual/latest/+` and
`+http://localhost:4000/dev-manual/latest/+`.
+
+After the first build, `./run-website-local.sh --fast` re-renders only the
manuals, which takes seconds.
+Run a full build again when you delete or rename a page: `--fast` does not
remove the pages it built before.
+
+The pages are under `latest`, not `next` as on the website: the build only
contains the version on your branch, so Antora publishes it as the latest one.
+
[NOTE]
====
This page is a scaffold. Still to write:
-* Building the documentation locally to preview it. The Antora playbook lives
in the Hop website repository, not this one; the exact steps need writing down.
* The AsciiDoc conventions this project actually follows: one sentence per
line, admonition usage, image sizing, how snippets under `pages/snippets` are
included.
* How a page reaches hop.apache.org, and how versioned manuals are cut at
release time.
====
