This is an automated email from the ASF dual-hosted git repository. ieugen pushed a commit to branch staging in repository https://gitbox.apache.org/repos/asf/james-site.git
commit 261ee67c447ea2cdf02240daa6e0cdacce453991 Author: Eugen Stan <ieu...@apache.org> AuthorDate: Fri Jul 31 02:17:16 2020 +0300 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 <ieu...@apache.org> --- README.adoc | 70 ++--------------------- antora-ui/build.gradle | 4 +- doc-sites/antora-playbook-local.yml | 40 +++++++++++++ doc-sites/antora-playbook.yml | 26 +++++++-- doc-sites/build.gradle | 2 +- docs/antora.yml | 4 ++ README.adoc => docs/modules/ROOT/pages/index.adoc | 0 7 files changed, 74 insertions(+), 72 deletions(-) diff --git a/README.adoc b/README.adoc index 7ecf936..b03f421 100644 --- a/README.adoc +++ b/README.adoc @@ -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. diff --git a/antora-ui/build.gradle b/antora-ui/build.gradle index 338262a..2445a1e 100644 --- a/antora-ui/build.gradle +++ b/antora-ui/build.gradle @@ -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') diff --git a/doc-sites/antora-playbook-local.yml b/doc-sites/antora-playbook-local.yml new file mode 100644 index 0000000..18b9bc8 --- /dev/null +++ b/doc-sites/antora-playbook-local.yml @@ -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 diff --git a/doc-sites/antora-playbook.yml b/doc-sites/antora-playbook.yml index 319655c..0f22923 100644 --- a/doc-sites/antora-playbook.yml +++ b/doc-sites/antora-playbook.yml @@ -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: HEAD + branches: master + start_path: docs + - url: https://gitbox.apache.org/repos/asf/james-postage.git + branches: master + start_path: docs + - url: https://gitbox.apache.org/repos/asf/james-site.git + branches: master 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 diff --git a/doc-sites/build.gradle b/doc-sites/build.gradle index 483412a..84d8a6f 100644 --- a/doc-sites/build.gradle +++ b/doc-sites/build.gradle @@ -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) diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 0000000..2e5257e --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,4 @@ +name: james-site +title: Apache James Site +version: 'latest' +prerelease: true diff --git a/README.adoc b/docs/modules/ROOT/pages/index.adoc similarity index 100% copy from README.adoc copy to docs/modules/ROOT/pages/index.adoc