DUE TO SPAM, SIGN-UP IS DISABLED. Goto Selfserve wiki signup and request an account.
Page History
...
How
...
we
...
make
...
API
...
references.
...
Under
...
construction.
...
| Table of Contents |
|---|
Overview
How do we create API documentation for CloudStack?
- Java Annotations in API code.
- Cosmetic touch-ups in doc generation code.
- 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
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
- Check out the code. Be in the right branch.
- In generatetocforuser.xsl, generatetocfordomainadmin.xsl, generatetocforadmin.xsl, generateadmincommands.xsl, generateusercommands.xsl, and generatedomainadmincommands.xsl, update the software version and any other boilerplate text.
- Check in your changes to the right branch.
XML to HTML using Jenkins
- Within a few minutes of checking in your cosmetic changes, you can get the new output. Go to (the build; coming soon!) depending on which branch you want. Under ‘Last Successful Artifacts’ you’ll see the zip file with everything in it.
- 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.
- 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.
- 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.
Overview
Content Tools