Skip to content
mod_cluster documentation sources and hosting
Branch: master
Clone or download
rhusar Merge pull request #11 from rhusar/MODCLUSTER-682
MODCLUSTER-682 Static legacy documentation
Latest commit 97de3e9 May 20, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.mvn/wrapper MODCLUSTER-688 Integrate Maven Wrapper Apr 12, 2019
docs Merge pull request #11 from rhusar/MODCLUSTER-682 May 20, 2019
.gitattributes MODCLUSTER-439 Overhaul distribution profile Aug 14, 2017
.gitignore
.travis.maven.settings.xml CI: Workaround non-https maven repository in travis default settings.xml Apr 12, 2019
.travis.yml Workaround non-https maven repository in travis default settings.xml Apr 12, 2019
LICENSE.txt MODCLUSTER-439 Overhaul distribution profile Aug 14, 2017
mvnw MODCLUSTER-688 Integrate Maven Wrapper Apr 12, 2019
mvnw.cmd MODCLUSTER-688 Integrate Maven Wrapper Apr 12, 2019
pom.xml MODCLUSTER-687 Ban non-https repositories Apr 12, 2019

README.adoc

Documentation 2.0 Build Status

Welcome to the new mod_cluster live documentation!

Contributing

How can I contribute?

  • Learn AsciiDoc.

  • Open http://docs.modcluster.io and locate section you want to contribute to.

  • Click 'Help us improve this section on GitHub!' at the top of each section.

  • If using an IDE, fork and clone the repository locally and navigate to docs/src/main/asciidoc/ directory.

  • Once finished editing, click 'Propose changes' which will open a new pull request.

  • Pull request will be quickly reviewed, merged and changes will be live almost instantly!

Guidelines

  • Documentation changes infrequently. To minimize the maintenance cost of multiple documentation versions, use working similar to "Since version 1.3" to describe behavior changes across versions.

  • Commit messages: you can describe changes you have done or you could leave the default GitHub message which will just say "Update section.adoc".

  • Use shorter lines to make rebasing and editing from the web easier.

  • Documentation always resides in upstream/master branch of this (docs.modcluster.io) repository.

Building locally

The build uses Maven.

[rhusar@ribera docs.modcluster.io]$ mvn clean install
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] mod_cluster docs (parent)                                          [pom]
[INFO] mod_cluster: Documentation                                         [pom]
[INFO]
[INFO] -----------< org.jboss.mod_cluster:mod_cluster-docs-parent >------------
[INFO] Building mod_cluster docs (parent) 2.0.0.Alpha1-SNAPSHOT           [1/2]
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- maven-clean-plugin:3.1.0:clean (default-clean) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-java-version) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-maven-version) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- buildnumber-maven-plugin:1.4:create (get-scm-revision) @ mod_cluster-docs-parent ---
[INFO] Executing: /bin/sh -c cd '/Users/rhusar/git/docs.modcluster.io' && 'git' 'rev-parse' '--verify' 'HEAD'
[INFO] Working directory: /Users/rhusar/git/docs.modcluster.io
[INFO] Storing buildNumber: cd1648f9bcf15c0b18eb401bff899d6aff2619f8 at timestamp: 1540404397386
[INFO] Storing buildScmBranch: master
[INFO]
[INFO] --- maven-source-plugin:3.0.1:jar-no-fork (attach-sources) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ mod_cluster-docs-parent ---
[INFO] Installing /Users/rhusar/git/docs.modcluster.io/pom.xml to /Users/rhusar/.m2/repository/org/jboss/mod_cluster/mod_cluster-docs-parent/2.0.0.Alpha1-SNAPSHOT/mod_cluster-docs-parent-2.0.0.Alpha1-SNAPSHOT.pom
[INFO]
[INFO] ---------------< org.jboss.mod_cluster:mod_cluster-docs >---------------
[INFO] Building mod_cluster: Documentation 2.0.0.Alpha1-SNAPSHOT          [2/2]
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- maven-clean-plugin:3.1.0:clean (default-clean) @ mod_cluster-docs ---
[INFO] Deleting /Users/rhusar/git/docs.modcluster.io/docs/target
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-java-version) @ mod_cluster-docs ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-maven-version) @ mod_cluster-docs ---
[INFO]
[INFO] --- buildnumber-maven-plugin:1.4:create (get-scm-revision) @ mod_cluster-docs ---
[INFO]
[INFO] --- asciidoctor-maven-plugin:1.5.6:process-asciidoc (pdf) @ mod_cluster-docs ---
[INFO] AsciiDoc processing is skipped.
[INFO]
[INFO] --- maven-source-plugin:3.0.1:jar-no-fork (attach-sources) @ mod_cluster-docs ---
[INFO]
[INFO] --- asciidoctor-maven-plugin:1.5.6:process-asciidoc (output-html) @ mod_cluster-docs ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 5 resources to images
[INFO] Copying 1 resource to .
[INFO] Rendered /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/index.adoc
[INFO]
[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ mod_cluster-docs ---
[INFO] Installing /Users/rhusar/git/docs.modcluster.io/docs/pom.xml to /Users/rhusar/.m2/repository/org/jboss/mod_cluster/mod_cluster-docs/2.0.0.Alpha1-SNAPSHOT/mod_cluster-docs-2.0.0.Alpha1-SNAPSHOT.pom
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] mod_cluster docs (parent) 2.0.0.Alpha1-SNAPSHOT .... SUCCESS [  1.035 s]
[INFO] mod_cluster: Documentation 2.0.0.Alpha1-SNAPSHOT ... SUCCESS [  3.612 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.798 s
[INFO] Finished at: 2018-10-24T20:06:41+02:00
[INFO] ------------------------------------------------------------------------

Resulting files are located in the docs/target/generated-docs/ directory.

Inner Workings

How does it work?

  1. Changes are proposed in a pull request for docs.modcluster.io repository.

  2. Changes are committed (merged) by a mod_cluster committer to the master branch.

  3. CI is notified by GitHub webhooks of the new HEAD revision.

  4. CI builds (and tests) the documentation.

  5. The job for master branch deploys the documentation.

  6. CI is configured with $GITHUB_TOKEN to authenticate as a docs bot with permissions for modcluster/docs.modcluster.io repository. Only the changes are committed.

  7. GitHub Pages picks up the changes and deploys the website.

Note
CNAME record is configured on the website pointing to GitHub servers.

Travis CI configuration uses deploy github extension and is configured as:

sudo: false
dist: trusty
language: java
script: mvn clean install
matrix:
  include:
    - env: JDK_RELEASE='OracleJDK 8'
      jdk: oraclejdk8
      deploy:
        provider: pages
        skip-cleanup: true
        repo: modcluster/docs.modcluster.io
        local-dir: docs/target/generated-docs/
        target-branch: gh-pages
        keep-history: true
        github-token: $GITHUB_TOKEN
        committer-from-gh: true
        email: docs-bot@modcluster.io
        allow-empty-commit: false
        verbose: true
        on:
          branch: master

Permissions/Token Setup

  1. Login as https://github.com/modcluster-docs-bot

  2. Go to Settings → Developer settings → Personal access tokens

  3. Generate new token with repo permissions

  4. Go to https://github.com/modcluster/docs.modcluster.io → Settings → Invite collaborators and grant modcluster-docs-bot write access (only needs the gh-pages branch).

  5. Accept invitation

  6. Add GITHUB_TOKEN to https://travis-ci.org/modcluster/docs.modcluster.io/settings

You can’t perform that action at this time.