Skip to content
Permalink
Browse files
JAMES-3226 #comment Added all sites to playbook
* Using bundled gulp-cli version
* Moved website docs to local docs module
* Readme should contain only link to online documentaton and this repo

Signed-off-by: Eugen Stan <ieugen@apache.org>
  • Loading branch information
ieugen committed Jul 30, 2020
1 parent 48df5f2 commit 0f05468d16b2ebdf36958288b786a283010849c7
Showing 7 changed files with 144 additions and 71 deletions.
@@ -1,71 +1,11 @@
= Apache James website

This repository is used for storing (some) content for https://james.apache.org[Apache James] website.

It's also used to build and publish the website.


== How to build the website

We use https://antora.org[Antora] as a tool to manage and generate the website.
We use https://gradle.org[Gradle] as a tool to drive / automate the tasks for generating, aggregating and publishing the website.


=== Why Antora?

Antora lets us aggregate multiple documentation sources, across multiple versions and publish them as a single website.
Documentation for each Apache James component is kept and versioned alongside the code for it.

=== Why Gradle?

Gralde allows us to autoamte the tasks that we do when publishing a website.
We write gradle tasks for building and publishing the website.
We can run those tasks locally and inside our CI infrastructure: https://builds.apache.org[Apache Builds].

More specifically, we use Gradle to:

* Download and install a specific version of https://nodejs.org[NodeJS] using https://github.com/node-gradle/gradle-node-plugin[Gradle Node Plugin]
* Install a local version of Antora
* Use a Gradle task to call build the website with Antora

By using this specific flow, you only need `git`, `Java` and shell access to build the website.
All other dependencies are installed automatically by Gradle.
Even Gradle is downloaded and installed using the Gradle wrapper script.
This repository is part of https://james.apache.org/[Apache James] project.

The sources are available here https://gitbox.apache.org/repos/asf#james and mirrored to Github.

== How to build the website

[source,bash]
----
# To build the website run
./gradlew clean build
# The website is located here
cd doc-sites/build/site
----


== How to customize the theme for the documentaion

The documentation website is based on https://antora.org[Antora].
We have added https://gitlab.com/antora/antora-ui-default/[antora-ui-default] project as a git subtree under `antora-ui`.

`./gradlew :antora-ui:build` will assemble the `antora-ui/build/ui-bundle.zip` archive required for the website.
All the steps are automated as Gradle tasks in that project.
All you have to do is change the css and html files and then rebuild the project.

The antora-ui project has a preview mode: `/.gradlew gulpPreviewTheme`


[source,shell]
----
# antora-ui-default was added like this. You should be able to pull some changes from upstream
git subtree add --prefix antora-ui https://gitlab.com/antora/antora-ui-default.git master --squash
----


=== Related links

* https://medium.com/@v/git-subtrees-a-tutorial-6ff568381844[A git subtree tutorial].
* https://docs.antora.org/antora/2.3/playbook/configure-ui/[Antora UI keys]
This repository is used for storing (some) content for https://james.apache.org[Apache James] website.

It's also used to build and publish the website.

Please see https://james.apache.org/james-site/latest/index.html[online documentation website] or the `docs/` folder.
@@ -16,14 +16,14 @@ node {
task gulpPreviewTheme(type: NpxTask) {
dependsOn npm_install
// https://gitlab.com/antora/antora-ui-default#user-content-preview-the-ui
command = 'gulp-cli@2.3.0'
command = 'gulp'
args = [ 'preview']
}

task gulpBuildBundle(type: NpxTask) {
// https://gitlab.com/antora/antora-ui-default#user-content-package-for-use-with-antora
dependsOn npm_install
command = 'gulp-cli@2.3.0'
command = 'gulp'
args = ["bundle"]

inputs.files('package.json', 'package-lock.json', '.gulp.json', 'gulpfile.js', 'index.js')
@@ -0,0 +1,40 @@
#
# Use this configuration for local testing / docs develop.
# You should clone all James repositories in the same place.
#
site:
title: Apache James
url: https://james.apache.org/
start_page: main::index.adoc
content:
sources:
- url: ./../../james-hupa
branches: HEAD
start_path: docs
- url: ./../../james-jdkim
branches: HEAD
start_path: docs
- url: ./../../james-jsieve
branches: HEAD
start_path: docs
- url: ./../../james-jspf
branches: HEAD
start_path: docs
- url: ./../../james-mime4j
branches: HEAD
start_path: docs
- url: ./../../james-project
branches: HEAD
start_path: docs
- url: ./../../james-postage
branches: HEAD
start_path: docs
- url: ./../
branches: HEAD
start_path: docs
ui:
bundle:
url: ./../antora-ui/build/ui-bundle.zip
# start_path: ui-bundle
runtime:
fetch: true
@@ -4,12 +4,30 @@ site:
start_page: main::index.adoc
content:
sources:
- url: https://gitbox.apache.org/repos/asf/james-hupa.git
branches: master
start_path: docs
- url: https://gitbox.apache.org/repos/asf/james-jdkim.git
branches: master
start_path: docs
- url: https://gitbox.apache.org/repos/asf/james-jsieve.git
branches: master
start_path: docs
- url: https://gitbox.apache.org/repos/asf/james-jspf.git
branches: master
start_path: docs
- url: https://gitbox.apache.org/repos/asf/james-mime4j.git
branches: master
start_path: docs
- url: https://gitbox.apache.org/repos/asf/james-project.git
branches: master
start_path: docs
- url: https://gitbox.apache.org/repos/asf/james-postage.git
branches: master
start_path: docs
- url: ./../
branches: HEAD
start_path: docs
# - url: https://gitbox.apache.org/repos/asf/james-jsieve.git
# branches: HEAD
# start_path: docs
ui:
bundle:
url: ./../antora-ui/build/ui-bundle.zip
@@ -19,7 +19,7 @@ task generateDocs(type: NpxTask) {
dependsOn npmInstall
dependsOn ':antora-ui:build'

inputs.files('package.json', 'package-lock.json', 'antora-playbook.yml')
inputs.files('package.json', 'package-lock.json', 'antora-playbook.yml', '*.yml')
inputs.dir(fileTree('node_modules').exclude('.cache'))
outputs.dir(siteOutputDir)

@@ -0,0 +1,4 @@
name: james-site
title: Apache James Site
version: 'latest'
prerelease: true
@@ -0,0 +1,71 @@
= Apache James website

This repository is used for storing (some) content for https://james.apache.org[Apache James] website.

It's also used to build and publish the website.


== How to build the website

We use https://antora.org[Antora] as a tool to manage and generate the website.
We use https://gradle.org[Gradle] as a tool to drive / automate the tasks for generating, aggregating and publishing the website.


=== Why Antora?

Antora lets us aggregate multiple documentation sources, across multiple versions and publish them as a single website.
Documentation for each Apache James component is kept and versioned alongside the code for it.

=== Why Gradle?

Gralde allows us to autoamte the tasks that we do when publishing a website.
We write gradle tasks for building and publishing the website.
We can run those tasks locally and inside our CI infrastructure: https://builds.apache.org[Apache Builds].

More specifically, we use Gradle to:

* Download and install a specific version of https://nodejs.org[NodeJS] using https://github.com/node-gradle/gradle-node-plugin[Gradle Node Plugin]
* Install a local version of Antora
* Use a Gradle task to call build the website with Antora

By using this specific flow, you only need `git`, `Java` and shell access to build the website.
All other dependencies are installed automatically by Gradle.
Even Gradle is downloaded and installed using the Gradle wrapper script.


== How to build the website

[source,bash]
----
# To build the website run
./gradlew clean build
# The website is located here
cd doc-sites/build/site
----


== How to customize the theme for the documentaion

The documentation website is based on https://antora.org[Antora].
We have added https://gitlab.com/antora/antora-ui-default/[antora-ui-default] project as a git subtree under `antora-ui`.

`./gradlew :antora-ui:build` will assemble the `antora-ui/build/ui-bundle.zip` archive required for the website.
All the steps are automated as Gradle tasks in that project.
All you have to do is change the css and html files and then rebuild the project.

The antora-ui project has a preview mode: `/.gradlew gulpPreviewTheme`


[source,shell]
----
# antora-ui-default was added like this. You should be able to pull some changes from upstream
git subtree add --prefix antora-ui https://gitlab.com/antora/antora-ui-default.git master --squash
----


=== Related links

* https://medium.com/@v/git-subtrees-a-tutorial-6ff568381844[A git subtree tutorial].
* https://docs.antora.org/antora/2.3/playbook/configure-ui/[Antora UI keys]


0 comments on commit 0f05468

Please sign in to comment.