Merge pull request xapi-project#3145 from kc284/master

Added option to generate the api reference in docbook format and prov…

Author: mseri

Makefile

@@ -13,7 +13,7 @@ build: setup.data
 doc: setup.data build
 	$(SETUP) -doc $(DOCFLAGS)
 	./jsapi.native -destdir _build/ocaml/doc -templdir ocaml/doc/templates
-	./datamodel_main.native -closed -markdown _build/ocaml/doc/markdown
+	./datamodel_main.native -closed -markdown -templdir ocaml/doc/templates _build/ocaml/doc/markdown
 	cp ocaml/doc/*.dot ocaml/doc/*.md ocaml/doc/doc-convert.sh _build/ocaml/doc/markdown
 
 test: setup.data build

_oasis

@@ -433,7 +433,8 @@ Executable datamodel_main
   Install:          false
   MainIs:           datamodel_main.ml
   BuildDepends:
-    xapi-datamodel
+    xapi-datamodel,
+    mustache
 
 
 ############################################################################

ocaml/doc/doc-convert.sh

@@ -7,22 +7,48 @@ GRAPHVIZ_FLAGS="-Tpng"
 dot vm-lifecycle.dot ${GRAPHVIZ_FLAGS} -o vm-lifecycle.png
 dot classes.dot ${GRAPHVIZ_FLAGS} -o classes.png
 
-if  [ ! "$1" = "--pdf" ]; then
+usage() {
+    echo "Usage:"
+    echo "    sh $0 [--pdf|--docbook]"
+}
+
+if [ "$#" -lt 1 ]; then
     exit 0
+elif [ "$#" -gt 1 ]; then
+    usage
+    exit 1
 fi
 
+OUTNAME=xenserver-management-api-guide
+
 FILES="
     basics.md
     wire-protocol.md
     vm-lifecycle.md
     api-ref-autogen.md
-    cover.yaml
 "
 
-PANDOC_FLAGS="
+PDF_FLAGS="
     --latex-engine=pdflatex
     --number-sections
     --chapters
+    --output=${OUTNAME}.pdf
+"
+
+DB_FLAGS="
+    --to=docbook
+    --output=${OUTNAME}.db
+    --template=template.db
 "
 
-pandoc ${FILES} ${PANDOC_FLAGS} -o xenserver-management-api-guide.pdf
+case "$1" in
+    --pdf)
+        pandoc ${FILES} cover.yaml ${PDF_FLAGS}
+        ;;
+    --docbook)
+        pandoc ${FILES} ${DB_FLAGS}
+        ;;
+    *)
+        usage
+        exit 1
+esac

ocaml/doc/jsapi.ml

@@ -103,20 +103,6 @@ let json_releases =
   in
   `O [ "releases", `A (List.map json_of_rel release_order) ]
 
-let json_current_version =
-  let time = Unix.gettimeofday () in
-  let month, year =
-     match String.split ' ' (Date.rfc822_to_string (Date.rfc822_of_float time)) with
-     | [ _; _; m; y; _; _ ] -> m,y
-     | _ -> failwith "Invalid datetime string"
-  in
-  `O [
-      "api_version_major", `Float (Int64.to_float api_version_major);
-      "api_version_minor", `Float (Int64.to_float api_version_minor);
-      "current_year", `String year;
-      "current_month", `String month;
-    ]
-
 let render_template template_file json output_file =
   let templ =  Stdext.Unixext.string_of_file template_file |> Mustache.of_string in
   let rendered = Mustache.render templ json in
@@ -137,11 +123,3 @@ let _ =
     (Filename.concat !templdir "branding.mustache")
     json_releases
     (Filename.concat !destdir "branding.js");
-
-  let markdown_dir = Filename.concat !destdir "markdown" in
-  Stdext.Unixext.mkdir_rec markdown_dir 0o755;
-
-  render_template
-    (Filename.concat !templdir "cover.mustache")
-    json_current_version
-    (Filename.concat markdown_dir "cover.yaml")

ocaml/doc/templates/docbook.mustache

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "../../../tools/docbook-xml/docbookx.dtd"[
+    <!ENTITY % local SYSTEM "local.ent">
+    <!ENTITY legal SYSTEM "shared/legal.ent">
+    <!ENTITY % ISOamsr SYSTEM "../../../tools/docbook-xml/ent/iso-amsr.ent">
+    <!ENTITY % ISOnum SYSTEM "../../../tools/docbook-xml/ent/iso-num.ent">
+
+    %local;
+    ]>
+
+<book lang="en">
+  <bookinfo id="bookinfo_titlestuff">
+    <title>&COMPANY_NAME_SHORT; &PRODUCT_BRAND; <trademark class="registered" role="die"/>
+      Management API
+    </title>
+    <subtitle>API Revision {{api_version_major}}.{{api_version_minor}}</subtitle>
+    <pubdate><?dbtimestamp format="B Y"?></pubdate>
+    <productnumber>&PRODUCT_VERSION;</productnumber>
+    <edition>1.0</edition>
+    <pubsnumber>&PRODUCT_BRAND;-&PRODUCT_VERSION;-&BUILD_NUMBER;</pubsnumber>
+    <copyright>
+      <year>&COPYRIGHT_YEARS;</year>
+      <holder>&COMPANY_NAME_LEGAL;</holder>
+    </copyright>&legal;
+  </bookinfo>
+
+  $for(include-before)$
+  $include-before$
+  $endfor$
+  $body$
+  $for(include-after)$
+  $include-after$
+  $endfor$
+
+</book>

ocaml/idl/datamodel_main.ml

@@ -25,13 +25,15 @@ let _ =
   and dtd_mode = ref false
   and closed = ref false (* shows release_closed *)
   and all = ref false (* shows release_impl as well *)
-  and dirname = ref "" in
+  and dirname = ref ""
+  and templdir = ref "" in
 
   Arg.parse [ "-dot", Arg.Set dot_mode, "output dot graph";
               "-markdown", Arg.Set markdown_mode, "output markdown document";
               "-dtd", Arg.Set dtd_mode, "output XML DTD";
               "-closed", Arg.Set closed, "output all OSS + closed API functions but not including internal ones";
-              "-all", Arg.Set all, "output all API functions, including internal ones"
+              "-all", Arg.Set all, "output all API functions, including internal ones";
+              "-templdir", Arg.Set_string templdir, "the directory with the template (mustache) files";
             ]
     (fun x -> dirname := x)
     "compile XenSource API datamodel specification";
@@ -67,7 +69,7 @@ let _ =
   let api = filter (fun _ -> true) (fun f -> not f.internal_only) (fun m -> not m.msg_hide_from_docs) api in
 
   if (!markdown_mode) then
-    Markdown_backend.all api !dirname;
+    Markdown_backend.all api !templdir !dirname;
 
   if !dirname <> "" then Unix.chdir !dirname;
   if !dot_mode then begin

ocaml/idl/markdown_backend.ml

@@ -423,8 +423,34 @@ Each possible error code is documented in the following section.
     (snd (List.split
             (List.sort (fun (n1, _) (n2, _)-> compare n1 n2) errs)))
 
-let all api destdir =
+let json_current_version =
+  let time = Unix.gettimeofday () in
+  let month, year =
+     match String.split ' ' (Date.rfc822_to_string (Date.rfc822_of_float time)) with
+     | [ _; _; m; y; _; _ ] -> m,y
+     | _ -> failwith "Invalid datetime string"
+  in
+  `O [
+      "api_version_major", `Float (Int64.to_float api_version_major);
+      "api_version_minor", `Float (Int64.to_float api_version_minor);
+      "current_year", `String year;
+      "current_month", `String month;
+    ]
+
+let render_template template_file json output_file =
+  let templ =  Stdext.Unixext.string_of_file template_file |> Mustache.of_string in
+  let rendered = Mustache.render templ json in
+  let out_chan = open_out output_file in
+  finally (fun () -> output_string out_chan rendered)
+          (fun () -> close_out out_chan)
+
+let all api templdir destdir =
   Stdext.Unixext.mkdir_rec destdir 0o755;
+
+  ["cover.mustache", "cover.yaml"; "docbook.mustache", "template.db"] |>
+  List.iter (fun (x,y) -> render_template
+    (Filename.concat templdir x) json_current_version (Filename.concat destdir y));
+
   let out_chan = open_out (Filename.concat destdir "api-ref-autogen.md") in
   let printer text =
     fprintf out_chan "%s" text;