How we make API references.

Overview

How do we create API documentation for CloudStack?

1. Java Annotations in API code.
2. Cosmetic touch-ups in doc generation code.
3. Java to HTML using Jenkins.

Annotations

Engineers include descriptive annotations when they write code. In Java, annotations start with @.
Some of the annotations we have defined to contain documentation strings look like this:

@Implementation(description="Creates an account", responseObject=UserResponse.class)
public class CreateAccountCmd extends BaseCmd {
public static final Logger s_logger = Logger.getLogger(CreateAccountCmd.class.getName());
private static final String s_name = "createaccountresponse";
/////////////////////////////////////////////////////
//////////////// API parameters /////////////////////
/////////////////////////////////////////////////////
@Parameter(name=ApiConstants.ACCOUNT, type=CommandType.STRING,
description="Creates the user under the specified account.")
private String accountName;

See the description=" " inside @Implementation and @Parameter. That text will be extracted in the Java to HTML step.

For more information, see Annotations in the API.

Java to HTML

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

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.

XML to HTML using Jenkins

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 Documentation.

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.