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

[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 EverettToews:
https://wiki.apache.org/jclouds/Publishing%20API%20docs?action=diff&rev1=13&rev2=14

- = 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. See [[https://issues.apache.org/jira/browse/JCLOUDS-147|JCLOUDS-147]] for ongoing work.
- 
  <<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. You have the software listed in [[How to Deploy Documentation]]
+  1. Maven 3+
  
+ == Publishing the Javadoc ==
-  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.
+ {{{
+ git clone https://git-wip-us.apache.org/repos/asf/jclouds-site.git
+ cd jclouds-site
+ ./deploy-javadoc.sh <JCLOUDS_VERSION>
+ }}}
  
- == Preparing the repository ==
+ <JCLOUDS_VERSION> is the version that has just been released. e.g. 1.7.3
  
- 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 have CSS styling, rather than being plain:
- {{attachment:javadocs-css-styling.png|with CSS styling|width=250}} {{attachment:javadocs-no-css-styling.png|plain|width=250}}
-  1. The last entries in the package list should be {{{org.jclouds.xml}}} and {{{org.jclouds.xml.internal}}}:
- {{attachment:check-package-list.png|package list|width=200}}
- 
- 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.
- 
- You can clean up the temporary branch of the jclouds repo ({{{1.6.3-site}}} in the example) when you're done.
- 
- == Publishing docs for jclouds-labs-openstack ==
- 
- Repeat the above process for [[https://git-wip-us.apache.org/repos/asf/jclouds-labs-openstack.git|jclouds-labs-openstack]], using the [[https://jclouds.ci.cloudbees.com/job/jclouds-labs-openstack-maven-site/|jclouds-labs-openstack Jenkins job]].
- 
- The Jenkins build should successfully run to completion in one go, so you can hopefully skip the "Updating aggregate Javadocs" and "Verifying updated Javadocs" steps here. The Javadocs will be rendered plain, though:
- 
- {{attachment:labs-openstack-javadocs-no-css-styling.png|plain|width=250}}
-