Documentation

This documentation is now part of the ovirt-engine-api-model repository, find it here:

https://github.com/oVirt/ovirt-engine-api-model

Introduction

This document describes how to contribute reference documentation for the API.

The specification of the API is written using Java as the supporting language.

Data types are represented by Java interfaces. For example, the Vm.java file contains the specification of the Vm entity, which looks like this:

@Type
public interface Vm extends VmBase {
    String stopReason();
    Date startTime();
    Date stopTime();
    ...
}

The methods of these interfaces represent the attributes of the data types, including their type and name.

Services API are also represented by Java interfaces. For example, the VmService.java file contains the specification of the Vm service, and it has content similar to this:

@Service
public interface VmService extends MeasurableService {
    interface Start {
        @In Boolean pause();
        @In Vm vm();
        @In Boolean useCloudInit();
        @In Boolean useSysprep();
        @In Boolean async();
    }
    ...
}

Operations are represented as nested interfaces. The names of these nested interfaces correspond to the names of the operations, and the methods correspond to the parameters of the operations.

The Java language supports adding documentation in the code itself, using the Javadoc comments. These comments start with /** and end with */ and can be added before the definition of any element, like interfaces and methods. These Javadoc comments are the mechanism that we use to document the specification. For example, the Vm type can be documented modifying the Vm.java file like this:

/**
 * Represents a virtual machine.
 */
@Type
public interface Vm extends VmBase {
    ...
}

Attributes can be documented in a similar way, just placing the Javadoc comment before the definition of the method that represents that attribute:

/**
 * Represents a virtual machine.
 */
@Type
public interface Vm extends VmBase {
    /**
     * Contains the reason why this virtual machine was stopped. This reason is
     * provided by the user, via the GUI or via the API.
     */
    String stopReason();
    ...
}

Same for services, their operations and their parameters:

/**
 * This service manages a specific virtual machine.
 */
@Service
public interface VmService extends MeasurableService {

    /**
     * This operation will start the virtual machine managed by this
     * service, if it isn't already running.
     */
    interface Start {
        /**
         * Specifies if the virtual machine should be started in pause
         * mode. It is an optional parameter, if not given then the
         * virtual machine will be started normally.
         */
        @In Boolean pause();
        ...
    }
    ...
}

These Javadoc comments are processed by tools that are part of the system and it is used to automatically generate the reference documentation. You can see an example of the generated documentation here.

This documentation viewer will eventually be part of the oVirt Engine server itself.

The Javadoc comments have their own format, but it isn't used by the our documentation tools. Instead of that the tools expect and support Markdown, in particular the GitHub variant. This means that Javadoc comments can contain rich text and examples. For example, you could write the following to better describe the Start operation of the Vm service:

/**
 * Specifies if the virtual machine should be started in pause
 * mode. It is an _optional_ parameter, if not given then the
 * virtual machine will be started normally.
 *
 * To use this parameter with the Python SDK you can use the
 * following code snippet:
 *
 * ` ` `python
 * # Find the virtual machine:
 * vm = api.vms.get(name="myvm")
 *
 * # Start the virtual machine paused:
 * vm.start(
 *   params.Action(
 *     pause=True
 *   )
 * )
 * ` ` `
 */
@In Boolean pause();

Contributing documentation

Cloning the `ovirt-engine` repository

The mechanism to contribute documentation is to modify the .java source files. This source code is part of the ovirt-engine project, which is hosted in gerrit.ovirt.org. So the first step to be able to contribute is to register to that system and prepare your environment for using git. For details see this.

To summarize, once you have registered and prepared your system to use git, this is the command that you need to execute in order to clone the ovirt-engine source:

$ git clone gerrit.ovirt.org:ovirt-engine

Locating the source file that you want to modify

The model source files are all inside the backend/manager/modules/restapi/model directory. For documentation purposes the most relevant files are the .java source files, which are inside the src/main/java directory. So you will probably want to change to that directory:

$ cd backend/manager/modules/restapi/model
$ cd src/main/java

This directory contains two sub-directories: types and services. The first is for the specifications of data types and the second for the specifications of services.

Files are named like the entities, so they should be easy to locate.

Modifying the source files

You can use your favorite editor to modify the source files. Just make sure to modify only the Javadoc comments.

Submitting the changes

Once you are happy with the changes that you made to the documentation you can prepare and submit a patch. For example, lets assume that you have modified the Vm.java file, this is what you will need to do to submit the patch:

$ git add types/Vm.java
$ git commit -s

This will open an editor where you can write the commit message. By default it will probaby be vim, but you can change it with the EDITOR environment variable:

$ export EDITOR=my-favorite-editor
$ git add types/Vm.java
$ git commit -s

In that editor you will be asked to write a commit message. It is important to write good commit messages, describing the reason for the change. The first line should be a summary, and should start with restapi:. Then a blank line and your description of the change. For example:

restapi: Improve the documentation of vm.start

This patch improves the documentation of the "vm.start"
operation, so that it is clear that the default value
of the "pause" parameter is "false".

Write the file, and you are ready to submit it:

$ git push origin HEAD:refs/for/master

If this finishes correctly it will give you the URL of the change. Go there and make sure that there is at least a reviewer for your change. In case of doubt add Juan Hernández as reviewer.

The reviewer may ask you to do changes to your patch, and will be happy to assist you with any doubts you have with the tools.

Eventually your patch will be merged and will be part of the reference documentation distributed with the next release of the software.

Testing and previewing your changes

If your changes are simple enough there may be no need to test them, just submit the patch. But if you are making larger changes you may want to se how they will look like in the generated documentation. Currently this process is a bit involved, but it will be easier in the future.

The first step is that you need to build the tools that process the documentation, and use them to generate the JSON representation of the model. These tools are part of the ovirt-engine repository that you have already cloned. To build it it is necessary to have Java and Maven installed. Won't go into the details here, but there are plenty of online resources that explain how to do it.

Once you have Java and Maven installed go to the ovirt-engine directory and run the mvn clean install -DskipTests command:

$ cd ovirt-engine
$ mvn clean install -DskipTests

The first time you do this it will take a long time, and it will download a good amount of stuff to your $HOME/.m2 directory. Be patient, next times it won't take that long, because you can build only the component that contains the model:

$ cd ovirt-engine
$ cd backend/manager/modules/restapi/interface/definition
$ mvn clean install -DskipTests

One of the results of this process will be a model.json file:

$ find . -name model.json
target/generated-resources/model.json

This file contains a description of the model, including the documentation. Take note of the location of this file, as it will be needed later.

The second step is to install the documentation viewer. This isn't currently part of the ovirt-engine repository, so you need to clone a different git repository, hosted in GitHub:

$ git clone https://github.com/jhernand/ovirt-api-explorer.git

This repository contains a JavaScript application. To use it it needs to be hosted in a web server. If you already have a running web server you can put the application there. Or you can also use npm. For more details see here.

Once this application is ready you can replace the model.json file that it contains with the one that you built in the previous step, reload the page and go to the relevant location. For example, assuming that you are using npm:

$ cd ovirt-api-exporer
$ cp .../model.json app/model.json
$ npm start

Then go with your browser to the relevant location:

http://localhost:8000/app/#/services/vm/methods/start

Feedback/questions/issues

If you have any question, issue, or feedback please contact Juan Hernández.

jhernand/DOCUMENTATION.md