...

For more information, see Annotations in the API.

Java to HTML Conversion Code

There is a script one piece of code that converts the Java annotations to XML output. Then there is a Java program another piece of code that takes in the xml XML for the table of contents as well as each command, and generates the required html HTML documents which we upload to our website.

The API doc building script is located at:

setup/apidoc/build-apidoc.sh

It calls the following to create intermediate XML output:

server/src/com/cloud/api/doc/ApiXmlDocWriter.java

After creating the XML files with ApiXmlDocWriter, the script calls the following:

setup/apidoc/XmlToHtmlConverter.java

This XmlToHtmlConverter uses a series of .xsl transforms (aka style sheets) to convert the XML to HTML. Those .xsl’s are all stored in:

setup/apidoc/*.xsl

Cosmetic Touch-Ups

1. Check out the code. Be in the right branch.
2. In generatetocforuser.xsl, generatetocfordomainadmin.xsl, generatetocforadmin.xsl, generateadmincommands.xsl, generateusercommands.xsl, and generatedomainadmincommands.xsl, update the software version and any other boilerplate text.
3. Check in your changes to the right branch.

...

1. Within a few minutes of checking in your cosmetic changes, you can get the new output. Go to jenkins.cloudstack.org and click the name of the build, depending on which branch you want. Under ‘Last Successful Artifacts’ you’ll see the zip file with everything in it.
2. Check the Build History, and make sure that the most recent build succeeded. If it didn’t, you will want to find out why and fix any important problems.
3. Assuming build success, grab that zip file, and unzip it on your machine. Your final unzipped output will be the ~/html folder, which will contain the dynamically generated content, and the static hardcoded files.
4. Upload the HTML to download.cloud.com as described in How to Publish CloudStack Documentationthe docs website (procedure: TODO. David Nalley).

Release Notes

There is a "diff.txt" file which is auto-generated. This lists all added, removed, and changed API commands versus the prior point release of CloudStack.