How we make API references.

Overview

How do we create API documentation for CloudStack?

...

The API documentation can be built with Maven using the following commands (should work on 4.1 and above):. The belt-and-braces approach which always work is to build everything:

1.  mvn -Pdeveloper -Dnoredist clean install

However if you've just edited the .xsl files since building you can use:

1. mvn -Pdeveloper -Dnoredist clean install
2. mvn clean install
3. mvn -P developer -pl :cloud-apidoc

Built The built documentation can then be found here: tools/apidoc/target/xmldoc/html

...

You can call it with the following command:

java -cp ~/.m2/repository/com/thoughtworks/xstream/xstream/1.4.310/xstream-1.4.310.jar:/path/to/source/cloudstack/dist/rpmbuild/BUILD/cloudstack-4.212.0-SNAPSHOT/server/target/classes \
com.cloud.api.doc.ApiXmlDocReader -old /path/to/4.011.commands.xml -new /path/to/4.112.commands.xml -d /path/to/diff/

...

1. You may have to update "tools/apidoc/gen_toc.py" and update the data structure: "known_categories" in case you add a command that it doesn't know how to categorize.
2. You cannot have empty descriptions in your annotations (like description=""). The XML parser python code will get mad and crash, forcing you to have to run build with -e and then go figure out what broke, so you can come back and update this documentation.. Thanks for doing -e and updating this wiki with this tip. !!