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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
