docs

Eclipse GlassFish Documentation

The subdirectories of this directory contain the Eclipse GlassFish website and documentation content, and the Maven projects to publish it.

The entire gh-pages content is published from here. DO NOT update the gh-pages branch directly.

The website project contains the top level web site content. The content is in src/main/resources.

The parent project effectively acts as an include file that contains all the common asciidoc configuration that the other projects need.

The distribution project combines all the separate documentation project contents into a single file, to make it convenient for the publish project to reference published versions of the documentation for previous releases.

The publish project contains the configuration to publish the entire web site.

Each of the documentation projects generates a jar file with the content for that document, using asciidoc. The content is installed with mvn install. The content of all these jar files is combined into a single jar file by the distribution project. Only this combined jar file needs to be deployed to Maven.

The publish project collects all of these distribution jar files for the current relase and previous releases using the maven-dependency-plugin, lays them out in the proper directory structure, and uses the maven-scm-publish-plugin to publish the content to the gh-pages branch of the GitHub repository.

For each of the documents, there's a current version published under the docs/SNAPSHOT directory, as well as stable released versions published under the docs/<version> directories. There's a docs/latest symlink that refers to the latest (final) release.

When a GlassFish release is done, the documents need to be generated and deployed, so that final version numbered documents will be in the Maven repository forever in the distribution artifact, and can be collected by the publish project to create the web site. The root pom.xml file needs to be updated to set the newly released version (e.g. the glassfish.version.7x property).

Preview the website in a forked Github repository

1. Run the following from this directory to build documentation and website modules:

mvn install

2. Then run the following to stage the Github pages resources:

mvn -pl website,distribution,publish -Ppublish-site install

3. Check out the gh-pages branch to a separate directory:

git clone --branch gh-pages https://github.com/eclipse-ee4j/glassfish.git /separate/directory

4. Copy the files from publish/target/staging to the other repository:

 cp -r publish/target/staging/* /separate/directory

5. Push to a forked repository

• create a fork in GitHub
• add the fork as a new remote to the other repository
• commit the changes to the gh-pages branch
• (force) push the gh-pages beanch: git -C /separate/directory push --force https://github.com/myfork/glassfish.git refs/heads/gh-pages:refs/heads/gh-pages (replace myfork with your GitHub username)

6. Preview the website

After some time, the preview will be available at (replace myfork with your GitHub username):

https://myfork.github.io/glassfish

Preview the website locally

It's possible to preview the website locally using a local Jekyll installation and procedure based on instructions for the jekyll-theme-eclipsefdn theme.

Pre-requisites:

• Ruby 2.1.0 or greater (check with ruby --version) - recommended to follow https://gorails.com/setup
• install bundler gem: gem install bundler

Instructions:

In the website directory generated by the publish module (publish/target/staging):

• create a file called Gemfile with the following contents:

source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
gem 'jekyll-theme-eclipsefdn'
gem 'webrick'

• modify the _config.yml file:
  • change line remote_theme: eclipsefdn/jekyll-theme-eclipsefdn to theme: jekyll-theme-eclipsefdn
  • add line repository: eclipse-ee4j/glassfish
• run: bundle install (Install Jekyll and other dependencies)
• preview the site: bundle exec jekyll serve

To Do

• Add a Jenkins job that waits for changes and publishes the web site.