Hide Forgot
Currently the reference documentation of the RESTAPI is written manually. As a result it requires a lot of effort and gets out of sync very quickly. To be able to have an updated reference documentation it is convenient to generate it automatically from the metadata provided by the engine, currently the XML schema of the entities and the RSDL document that describes the capabilities of the resources. There are two main tasks that we will need to do: 1. We will need to create a mechanism to associate pieces of documentation with the descriptions of the entities and resources. These could be documentation annotations in the XML schema, documentation elements in the RSDL metadata file, documentation comments in the Java interfaces of the resources, or any other mechanism that we consider appropriate. We will also need to create a tool to extract those pieces of documentation and to generate the actual documents. These could be similar to the tools that we use to generate the Python and Java SDKs. 2. We will need to actually write the pieces of documentation. The first task is technically complicated, but feasible. It will require an amount of effort similar to the initial creation of the Python or Java SDKs. The second task isn't technically complicated, but it requires a lot of work, probably by multiple people, as no one knows completely all capabilities of the RESTAPI.
Target release should be placed once a package build is known to fix a issue. Since this bug is not modified, the target version has been reset. Please use target milestone to plan a fix for a oVirt release.
The first steps towards addressing this issue have already been taken. The API has now a specification language (the metamodel) and it will soon have a way to deliver it to users, in its source form and also in XML and JSON: https://gerrit.ovirt.org/#/q/status:open+project:ovirt-engine+branch:master+topic:metamodel_server My suggestion for generating the documentation is to create a web application that users can use to explore the documentation of the API. I have created a prototype of that web application here: https://github.com/jhernand/ovirt-api-explorer This application is intended to be eventually included in the server, and also to be used standalone, as purely static content. An example is available here: https://jhernand.fedorapeople.org/ovirt-api-explorer
There haven't been any advances in adding the documentation to the model repository described in comment 2. So even if the mechanism is ready, there won't probably be any useful content ready for version 4.0 of the engine. So I'm re-targeting to 4.1.
The fix for this issue should be included in oVirt 4.1.0 beta 1 released on December 1st. If not included please move back to modified.
Link on welcome page is functional. I tried to click randomly around the document links and in left menu tree. All was OK. By resizing browsers window page refreshes OK. verified in ovirt-engine-4.1.0-0.3.beta2.el7.noarch tested in Firefox 50.1.0 and Google Chrome 55.0
relevant test case: RHEVM3-8689