[Jclouds Wiki] Update of "Publishing API docs" by AndrewPhillips

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jclouds Wiki" for change notification.

The "Publishing API docs" page has been changed by AndrewPhillips:
https://wiki.apache.org/jclouds/Publishing%20API%20docs

New page:
= How to publish the Maven site (including Javadocs) for Apache jclouds =

The current process leaves - shall we say - "room for optimization", so any improvement suggestions are appreciated.

<<TableOfContents(3)>>

== Prerequisites ==

Parts of this process require the following two conditions to be met:

 1. The release tag has been pushed to the ASF Git repo
 1. The released JARs have been synced to Maven Central

It's easiest to wait until this has occurred before starting.

== Preparing the repository ==

The Maven sites are currently hosted on !GitHub, using [[https://pages.github.com/|GitHub Pages]]. Each release is hosted in its own repository. To prepare a repository for the site for a new release:

 1. Create a new repository under any !GitHub account, e.g. [[https://github.com/demobox/jclouds-maven-site-1.6.3|demobox/jclouds-maven-site-1.6.3]]
 1. Disable ''Wikis'' and ''Issues'' for the repo (under ''Settings'')
 1. Clone the repo, and add an empty {{{.nojekyll}}} and {{{README.md}}} ([[https://raw.githubusercontent.com/demobox/jclouds-maven-site-1.6.3/gh-pages/README.md|example]]) under the repo root
 1. Commit, rename the {{{master}}} branch to {{{gh-pages}}} and push

== Running the Jenkins job ==

Once the release tag has been pushed to the ASF Git repo and the release JARs have been synced to Maven Central, run the [[https://jclouds.ci.cloudbees.com/job/jclouds-maven-site/|jclouds-maven-site Jenkins job]] to publish the site

 1. Example parameters:
   1. {{{RELEASE_VERSION}}}: {{{1.6.3}}}
   1. {{{MVN_SITE_REPO}}}: {{{gitsite:git@github.com/demobox/jclouds-maven-site-1.6.3.git}}} (should match the repo created in the previous step)
   1. Leave {{{MVN_RESUME_FROM}}} blank initially
 1. The Maven site build may fail a couple of times before running to the end. When the build fails, resume it from the failed project using the {{{MVN_RESUME_FROM}}} argument. E.g. if the build fails in {{{aws-ec2}}}, re-run from that project using
   1. {{{MVN_RESUME_FROM}}}: {{{-rf :aws-ec2}}}

== Updating aggregate Javadocs ==

Unfortunately, the Jenkins build does not always correctly generate the aggregate Javadocs. Even when it does, it does not correctly process the CSS, so it makes sense to update the aggregate Javadocs in any case.

 1. Clone or update the site repository (the repository created in the first step)
 1. Clone the [[https://git-wip-us.apache.org/repos/asf/jclouds.git|ASF jclouds repo]], if not already done
 1. Create a temporary branch off the release branch and revert to the release commit, e.g.
{{{
git checkout 1.6.x
git checkout -b 1.6.3-site
git reset --hard jclouds-1.6.3
}}}
 1. Generate the aggregate Javadoc. You may need to allocate more memory to the process, e.g. I run
{{{
mvn clean javadoc:aggregate -DadditionalJOption=-J-Xmx512m
}}}
 1. Copy the generated Javadoc (the {{{target/site/apidocs}}} folder in the jclouds repo) into {{{<release version>/jclouds}}} (e.g. {{{1.6.3/jclouds}}}) in the site repo. Overwrite any existing files if prompted
 1. Add all changed files and [[https://github.com/demobox/jclouds-maven-site-1.6.3/commit/150da9bceac11440aa9c8a788e8b13f188e69031|commit the changes]] to the site repo
 1. Push the commit to the site repo

== Verifying updated Javadocs ==

After giving !GitHub a couple of minutes to render the updated Javadocs, check for the following two things:

 1. The CSS styling should look like this, rather than like this
 1. The last entries in the package list should be {{{org.jclouds.xml}}} and {{{org.jclouds.xml.internal}}}

If either of those two is not the case, check the aggregate Javadocs you generated locally in the third step. You may need to repeat that step, or the subsequent repo update and push.