You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by jh...@apache.org on 2026/02/27 07:50:35 UTC
(james-project) 03/03: [JAMES-4175] fix website build instructions
This is an automated email from the ASF dual-hosted git repository.
jhelou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit e28b26bd86eee68bb058d40b70f9e483570b8b53
Author: Jean Helou <je...@xn--gml-cma.com>
AuthorDate: Thu Feb 26 07:24:18 2026 +0100
[JAMES-4175] fix website build instructions
Ensures README is always aligned with antora build section in community/websitew
---
docs/README.adoc | 1 +
docs/README.md | 33 --------------
docs/modules/community/pages/website.adoc | 68 ++++++++++++++++++++---------
docs/modules/community/partials/antora.adoc | 60 +++++++++++++++++++++++++
4 files changed, 109 insertions(+), 53 deletions(-)
diff --git a/docs/README.adoc b/docs/README.adoc
new file mode 120000
index 0000000000..292bc3f151
--- /dev/null
+++ b/docs/README.adoc
@@ -0,0 +1 @@
+docs/modules/community/partials/antora.adoc
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 2b5b72e315..0000000000
--- a/docs/README.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Building and serving documentation locally
-
-## Executing within source code
-
-(Clone `https://github.com/apache/james-project` locally, go into `docs` folder)
-
-**Step 1**: [Install Antora](https://docs.antora.org/antora/latest/install-and-run-quickstart/)
-
-**Step 2**: Build the Antora content locally
-
-```
-antora antora-playbook-local.yml
-```
-
-**Step 3**: Open `build/site/index.html` in your browser.
-
-## Building with Dockerfile
-
-To build the document from apache-james repository, you can use the Dockerfile provided in this folder.
-
-Build the Docker image:
-
-```
-docker build --build-arg JAMES_CHECKOUT=master -f Dockerfile -t james-site-antora .
-```
-
-Then run the Docker image:
-
-```
-docker run -p 80:80 james-site-antora
-```
-
-Go to `http://localhost` in your browser.
diff --git a/docs/modules/community/pages/website.adoc b/docs/modules/community/pages/website.adoc
index 69bff57cc2..4ece0bb671 100644
--- a/docs/modules/community/pages/website.adoc
+++ b/docs/modules/community/pages/website.adoc
@@ -1,7 +1,9 @@
= Building and publishing the website
:path: src/homepage
-The source code of website https://james.apache.org[james.apache.org] is located in {path}.
+The source code of website https://james.apache.org[james.apache.org] is
+located in {path}.
+
Here are the instructions how to publish new changes to the website.
The website is currently composed of the output of
@@ -12,9 +14,11 @@ The website is currently composed of the output of
[WARNING]
.https://issues.apache.org/jira/browse/JAMES-3187[Documentation migration]
====
-We are migrating the content of the maven site to use antora documentation instead.
+We are migrating the content of the maven site to use xref:_building_the_next_gen_documentation[antora documentation] instead.
-Most of the useful content has been migrated but the new documentation is not yet published to the main site. It can be found on the https://james.staged.apache.org[staging version] of the website.
+Most of the useful content has been migrated but the new documentation is not
+yet published to the main site. It can be found on the
+https://james.staged.apache.org[staging version] of the website.
====
== Building the homepage
@@ -25,7 +29,8 @@ You can use jekyll to build the website. Go into `{path}` and run the following
$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jekyll/jekyll:$JEKYLL_VERSION jekyll build
----
-The resulting deployable content will be available in the `{path}/_site/` directory.
+The resulting deployable content will be available in the `{path}/_site/`
+directory.
In order to test the homepage, you can use this command:
[,shell]
@@ -35,7 +40,8 @@ $ docker run --rm -v $PWD/site:/srv/jekyll -p 4000:4000 -it jekyll/jekyll jekyl
The site will be available at http://localhost:4000/
-If you need to update the current site, checkout the branch asf-site from Apache git:
+If you need to update the current site, checkout the branch asf-site from
+Apache git:
[,shell]
----
$ git clone https://git-wip-us.apache.org/repos/asf/james-site.git
@@ -43,7 +49,8 @@ $ cd james-site
$ git checkout origin/asf-site -b asf-site
----
-And replace in the previous commands `$PWD/site` by `<james-site-clone-directory>/content`, for example:
+And replace in the previous commands `$PWD/site` by
+`<james-site-clone-directory>/content`, for example:
[,shell]
----
@@ -58,22 +65,27 @@ $ cd ../james-site
$ git push origin asf-site
----
-## Maven site
+== Maven site
-The maven site deploy phase uses and requires locally configuring credentials to enable ssh access. See
+The maven site deploy phase uses and requires locally configuring credentials to
+enable ssh access. See
http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html[maven-deploy-plugin's documentation] for more details on achieving this.
-### Manually
+WARNING: Generating the full maven site with all reports takes a long time
+(as in hours)
+
+=== Manually
1. Install Apache Maven 3.0.2+ and make its binary 'mvn' available on your PATH.
See http://maven.apache.org/download.html#Installation.
-2. run `mvn clean site`
+2. run `mvn clean package site -Djib.skip`
3. Test the built site in your browser from the `{path}/target/site` folder
4. If everything looks OK, deploy the site using `mvn clean site-deploy`.
-5. Wait for the changes to replicate to the Apache web server or setup 140.211.11.10:80 as
-a proxy to review the changes (described here: http://www.apache.org/dev/project-site.html)
+5. Wait for the changes to replicate to the Apache web server or setup
+140.211.11.10:80 as a proxy to review the changes (described here:
+http://www.apache.org/dev/project-site.html)
-### Docker
+=== Docker
Can be used only to build the site locally
@@ -94,18 +106,34 @@ $ docker build -t james/site src/site-docker
$ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/site:/destination james/site master
----
-### nix development shell
+=== Nix development shell
-Enter the xref:contributing.adoc#_experimental_nix_support[james experimental development shell]
+Enter the xref:contributing.adoc#_experimental_nix_support[james experimental
+development shell]
-1. run `mvn clean site`
+1. run `mvn clean package site -Djib.skip`
2. Test the built site in your browser from the `{path}/target/site` folder
3. If everything looks OK, deploy the site using `mvn clean site-deploy`.
-4. Wait for the changes to replicate to the Apache web server or setup 140.211.11.10:80 as
-a proxy to review the changes (described here: http://www.apache.org/dev/project-site.html)
+4. Wait for the changes to replicate to the Apache web server or setup
+140.211.11.10:80 as a proxy to review the changes
+(see: http://www.apache.org/dev/project-site.html)
+
+=== Technical reports
+
+To deploy the technical reports use any of the 3 ways above adding the
+`-Psite-reports` profile.
+
+== Building the next gen documentation
-### Technical reports
+The old maven site is quite painful to maintain and doesn't allow for
+versionning of the content per releases which motivated the
+https://issues.apache.org/jira/browse/JAMES-3187[migration effort].
-To deploy the technical reports use any of the 3 ways above adding the `-Psite-reports` profile.
+Most of the maven site content has been migrated to asciidoc files assembled by
+antora. You can preview the content at https://james.staged.apache.org, this
+documentation is published automatically by the james CI.
+This new documentation root is located in the `docs` directory and includes
+these build instructions.
+include::partial$antora.adoc[]
diff --git a/docs/modules/community/partials/antora.adoc b/docs/modules/community/partials/antora.adoc
new file mode 100644
index 0000000000..fedaff768d
--- /dev/null
+++ b/docs/modules/community/partials/antora.adoc
@@ -0,0 +1,60 @@
+== Building the next gen documentation
+:page-partial:
+
+The old maven site is quite painful to maintain and doesn't allow for
+versionning of the content per releases which motivated the
+https://issues.apache.org/jira/browse/JAMES-3187[migration effort].
+
+Most of the maven site content has been migrated to asciidoc files assembled by
+antora. You can preview the content at https://james.staged.apache.org, this
+documentation is published automatically by the james CI.
+
+This new documentation root is located in the `docs` directory and includes
+these build instructions.
+
+=== Executing within source code
+
+(Clone `https://github.com/apache/james-project` locally, go into `docs` folder)
+
+. https://docs.antora.org/antora/latest/install-and-run-quickstart/[Install Antora]
+
+. Build the Antora content locally
++
+[,shell]
+----
+ $ antora antora-playbook-local.yml
+----
++
+. Open `build/site/index.html` in your browser.
+
+=== Building with Dockerfile
+
+To build the document from apache-james repository, you can use the Dockerfile provided in this folder.
+
+Build the Docker image:
+
+----
+docker build --build-arg JAMES_CHECKOUT=master -f Dockerfile -t james-site-antora .
+----
+
+Then run the Docker image:
+
+----
+docker run -p 80:80 james-site-antora
+----
+
+Go to `http://localhost` in your browser.
+
+=== Build with the nix enviroment
+
+Enter the xref:contributing.adoc#_experimental_nix_support[james experimental
+development shell]
+
+. Build the Antora content locally
++
+[,shell]
+----
+ $ antora antora-playbook-local.yml
+----
++
+. Open `build/site/index.html` in your browser.
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org