Split the API reference markdown into smaller files and use templates…

… to generate it.

Signed-off-by: Konstantina Chremmou <[email protected]>

Makefile

@@ -42,15 +42,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,3 +1,7 @@
+---
+ layout: doc
+---
+
 # API Basics
 
 This document defines the XenServer Management API - an interface for remotely

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.

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

@@ -5985,7 +5985,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 +6202,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 +6889,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 +7042,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 +7357,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 +7627,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_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

@@ -1368,7 +1368,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)