Merge pull request xapi-project#5338 from kc284/api-ref

Makefile

@@ -74,15 +74,20 @@ schema:
 	dune runtest ocaml/idl
 
 doc:
-	dune build --profile=$(PROFILE) ocaml/idl/datamodel_main.exe
+#html
 	dune build --profile=$(PROFILE) -f @ocaml/doc/jsapigen
 	mkdir -p $(XAPIDOC)/html
 	cp -r _build/default/ocaml/doc/api $(XAPIDOC)/html
 	cp _build/default/ocaml/doc/branding.js $(XAPIDOC)/html
 	cp ocaml/doc/*.js ocaml/doc/*.html ocaml/doc/*.css $(XAPIDOC)/html
-	dune exec --profile=$(PROFILE) -- ocaml/idl/datamodel_main.exe -closed -markdown $(XAPIDOC)/markdown
-	cp ocaml/doc/*.dot ocaml/doc/doc-convert.sh $(XAPIDOC)
+#markdown
+	dune build --profile=$(PROFILE) -f @ocaml/idl/markdowngen
+	mkdir -p $(XAPIDOC)/markdown
+	cp -r _build/default/ocaml/idl/autogen/*.md $(XAPIDOC)/markdown
+	cp -r _build/default/ocaml/idl/autogen/*.yml $(XAPIDOC)/markdown
 	find ocaml/doc -name "*.md" -not -name "README.md" -exec cp {} $(XAPIDOC)/markdown/ \;
+#other
+	cp ocaml/doc/*.dot ocaml/doc/doc-convert.sh $(XAPIDOC)
 # Build manpages, networkd generated these
 	dune build --profile=$(PROFILE) -f @man
 

ocaml/doc/basics.md

@@ -1,12 +1,16 @@
+---
+ layout: doc
+---
+
 # API Basics
 
 This document defines the XenServer Management API - an interface for remotely
-configuring and controlling virtualised guests running on a Xen-enabled host.
+configuring and controlling virtualized guests running on a Xen-enabled host.
 
 The API is presented here as a set of Remote Procedure Calls (RPCs). There are
 two supported wire formats, one based upon [XML-RPC](http://xmlrpc.scripting.com/spec.html)
 and one based upon [JSON-RPC](http://www.jsonrpc.org) (v1.0 and v2.0 are both
-recognised). No specific language bindings are prescribed, although examples
+recognized). No specific language bindings are prescribed, although examples
 will be given in the python programming language.
 
 Although we adopt some terminology from object-oriented programming,

ocaml/doc/vm-lifecycle.md

@@ -1,3 +1,7 @@
+---
+ layout: doc
+---
+
 # VM Lifecycle
 
 The following diagram shows the states that a VM can be in

ocaml/doc/wire-protocol.md

@@ -1,3 +1,7 @@
+---
+ layout: doc
+---
+
 # Wire Protocol for Remote API Calls
 
 API calls are sent over a network to a Xen-enabled host using an RPC protocol.
@@ -178,7 +182,7 @@ following manner:
 
 * our `void` type is transmitted as an empty string.
 
-Both versions 1.0 and 2.0 of the JSON-RPC wire format are recognised and,
+Both versions 1.0 and 2.0 of the JSON-RPC wire format are recognized and,
 depending on your client library, you can use either of them.
 
 ### JSON-RPC v1.0
@@ -486,7 +490,7 @@ session reference is returned under the key `Value` in the resulting dictionary
 ...                                           "version", "originator")['Value']
 ```
 
-This is what the call looks like when serialised
+This is what the call looks like when serialized
 
 ```xml
 <?xml version='1.0'?>
@@ -530,7 +534,7 @@ Once a reference to a VM has been acquired, a lifecycle operation may be invoked
 In this case the `start` message has been rejected, because the VM is
 a template, and so an error response has been returned.  These high-level
 errors are returned as structured data (rather than as XML-RPC faults),
-allowing them to be internationalised.
+allowing them to be internationalized.
 
 Rather than querying fields individually, whole _records_ may be returned at once.
 To retrieve the record of a single object as a python dictionary:
@@ -575,7 +579,7 @@ reference:
 ...                       "user", "passwd", "version", "originator")
 ```
 
-`pyjsonrpc` uses the JSON-RPC protocol v2.0, so this is what the serialised
+`pyjsonrpc` uses the JSON-RPC protocol v2.0, so this is what the serialized
 request looks like:
 
 ```json
@@ -623,7 +627,7 @@ Once a reference to a VM has been acquired, a lifecycle operation may be invoked
 
 In this case the `start` message has been rejected because the VM is
 a template, hence an error response has been returned. These high-level
-errors are returned as structured data, allowing them to be internationalised.
+errors are returned as structured data, allowing them to be internationalized.
 
 Rather than querying fields individually, whole _records_ may be returned at once.
 To retrieve the record of a single object as a python dictionary:

ocaml/idl/autogen/api-ref-autogen.md

@@ -0,0 +1,12 @@
+---
+ layout: doc
+---
+
+# API Reference
+
+Version **@xapi-version@**
+
+-  [Classes](@root@management-api/classes.html)
+-  [Relationships Between Classes](@root@management-api/relationships-between-classes.html)
+-  [Types](@root@management-api/types.html)
+-  [ErrorHandling](@root@management-api/api-ref-autogen-errors.html)

ocaml/idl/autogen/dune

@@ -0,0 +1,6 @@
+(alias
+  (name markdowngen)
+  (deps
+    (source_tree .)
+  )
+)

ocaml/idl/datamodel.ml

@@ -2057,7 +2057,10 @@ module Bond = struct
   let t =
     create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None
       ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_bond
-      ~descr:"" ~gen_events:true ~doccomments:[]
+      ~descr:
+        "A Network bond that combines physical network interfaces, also known \
+         as link aggregation"
+      ~gen_events:true ~doccomments:[]
       ~messages_default_allowed_roles:_R_POOL_OP ~doc_tags:[Networking]
       ~messages:[create; destroy; set_mode; set_property]
       ~contents:
@@ -5985,7 +5988,7 @@ module DR_task = struct
           )
         ; (Set String, "whitelist", "The devices to use for disaster recovery")
         ]
-      ~result:(Ref _dr_task, "The reference to the created task")
+      ~result:(Ref _dr_task, "The reference of the created DR_task")
       ~doc:
         "Create a disaster recovery task which will query the supplied list of \
          devices"
@@ -6202,7 +6205,7 @@ module Blob = struct
           }
         ]
       ~doc:"Create a placeholder for a binary blob" ~flags:[`Session]
-      ~result:(Ref _blob, "The reference to the created blob")
+      ~result:(Ref _blob, "The reference of the created blob")
       ~allowed_roles:_R_POOL_OP ()
 
   let destroy =
@@ -6889,7 +6892,8 @@ module GPU_group = struct
           ; param_default= Some (VMap [])
           }
         ]
-      ~result:(Ref _gpu_group, "") ~allowed_roles:_R_POOL_OP ()
+      ~result:(Ref _gpu_group, "The reference of the created GPU_group")
+      ~allowed_roles:_R_POOL_OP ()
 
   let destroy =
     call ~name:"destroy"
@@ -7041,7 +7045,7 @@ module VGPU = struct
           ; param_default= Some (VRef null_ref)
           }
         ]
-      ~result:(Ref _vgpu, "reference to the newly created object")
+      ~result:(Ref _vgpu, "The reference of the created VGPU object")
       ~allowed_roles:_R_POOL_OP ()
 
   let destroy =
@@ -7356,7 +7360,7 @@ module PVS_proxy = struct
 
   let create =
     call ~name:"create" ~doc:"Configure a VM/VIF to use a PVS proxy"
-      ~result:(Ref _pvs_proxy, "the new PVS proxy")
+      ~result:(Ref _pvs_proxy, "The reference of the created PVS proxy")
       ~params:
         [
           (Ref _pvs_site, "site", "PVS site that we proxy for")
@@ -7626,7 +7630,8 @@ module USB_group = struct
           ; param_default= Some (VMap [])
           }
         ]
-      ~result:(Ref _usb_group, "") ~allowed_roles:_R_POOL_ADMIN ()
+      ~result:(Ref _usb_group, "The reference of the created USB_group")
+      ~allowed_roles:_R_POOL_ADMIN ()
 
   let destroy =
     call ~name:"destroy" ~lifecycle

ocaml/idl/datamodel_certificate.ml

@@ -34,7 +34,8 @@ let certificate_type =
     )
 
 let t =
-  create_obj ~name:_certificate ~descr:"Description" ~doccomments:[]
+  create_obj ~name:_certificate
+    ~descr:"An X509 certificate used for TLS connections" ~doccomments:[]
     ~gen_constructor_destructor:false ~gen_events:true ~in_db:true ~lifecycle
     ~persist:PersistEverything ~in_oss_since:None
     ~messages_default_allowed_roles:_R_READ_ONLY

ocaml/idl/datamodel_errors.ml

@@ -1455,7 +1455,7 @@ let _ =
     ~doc:
       "The requested update could not be found. Please upload the update \
        again. This can occur when you run xe update-pool-clean before xe \
-       update-apply. "
+       update-apply."
     () ;
   error Api_errors.update_pool_apply_failed ["hosts"]
     ~doc:"The update cannot be applied for the following host(s)." () ;

ocaml/idl/datamodel_host.ml

@@ -1369,7 +1369,7 @@ let set_power_on_mode =
       ; (Changed, rel_stockholm, "Removed iLO script")
       ]
     ~in_product_since:rel_midnight_ride
-    ~doc:"Set the power-on-mode, host, user and password "
+    ~doc:"Set the power-on-mode, host, user and password"
     ~params:
       [
         (Ref _host, "self", "The host")

ocaml/idl/datamodel_main.ml

@@ -86,7 +86,7 @@ let _ =
   in
 
   if !markdown_mode then
-    Markdown_backend.all api !dirname ;
+    Markdown_backend.all api ;
 
   if !dirname <> "" then Unix.chdir !dirname ;
   if !dot_mode then

ocaml/idl/dune

@@ -30,13 +30,24 @@
   (modules datamodel_main dot_backend dtd_backend markdown_backend)
   (libraries
     dune-build-info
+    mustache
     xapi-datamodel
     xapi-stdext-std
     xapi-stdext-pervasives
     xapi-stdext-unix
   )
 )
 
+(rule
+  (alias markdowngen)
+  (deps
+    (:x datamodel_main.exe)
+    (source_tree templates)
+  )
+  (package xapi-datamodel)
+  (action (run %{x} -closed -markdown))
+)
+
 (test
   (name schematest)
   (modes exe)