[server] generated doc enhancements

doc/pandoc/style.css

@@ -36,7 +36,7 @@ body {
     height: 100%;
     overflow: hidden;
     font-family: "Verdana", sans;
-    font-size: 12pt;
+    font-size: 10pt;
 }
 
 /* -------------------------------------------------------------------------- */
@@ -72,7 +72,7 @@ body {
     justify-content: left ;
     align-content: center ;
     box-sizing: border-box ;
-    width: 18cm ;
+    width: 22cm ;
     height: 100% ;
     padding: 0cm 1cm 1cm 1cm ;
 }
@@ -81,10 +81,6 @@ body {
 /* --- Navigation                                                         --- */
 /* -------------------------------------------------------------------------- */
 
-#TOC {
-    font-size: smaller ;
-}
-
 #NAVIGATION a {
     color: black ;
 }
@@ -92,7 +88,7 @@ body {
 #NAVIGATION a.root {
     display: block;
     font-family: "Optima", "Verdana", "Arial", sans;
-    font-size: 16pt;
+    font-size: 10pt;
     margin-top: 1cm;
     margin-bottom: 6mm;
 }
@@ -123,7 +119,7 @@ body {
 /* -------------------------------------------------------------------------- */
 
 h1 {
-    width: 18cm;
+    width: 22cm;
     font-family: "Optima", "Verdana", "Arial", sans;
     text-align: left;
     margin-top: 1cm;
@@ -141,7 +137,7 @@ h2 {
 }
 
 h3 {
-    width: 17cm;
+    width: 18cm;
     font-family: "Optima", "Verdana", "Arial", sans;
     margin-top: 5mm;
     margin-bottom: 3mm;
@@ -158,11 +154,11 @@ h4,h5,h6 {
     font-weight: bold;
 }
 
-p { margin: 18px 0px 18px 0px; width: 15cm; }
+p { margin: 18px 0px 18px 0px; width: 18cm; }
 
 ul,ol,blockquote {
     margin-left: 24px ;
-    width: 13cm;
+    width: 15cm;
 }
 
 li {
@@ -188,10 +184,13 @@ hr {
 
 table {
     border-collapse: collapse ;
+    margin-top: 4mm ;
+    margin-bottom: 4mm ;
     margin-left: 6mm ;
 }
 
 th,td {
+    font-weight: normal ;
     padding: 2px 16px 2px 12px ;
 }
 

src/plugins/server/data.ml

@@ -63,7 +63,7 @@ let failure ?json msg =
 let failure_from_type_error msg json =
   failure ~json "%s" msg
 
-let page = Doc.page `Kernel ~title:"Kernel Types" ~filename:"data.md"
+let page = Doc.page `Kernel ~title:"Basic Types" ~filename:"data.md"
 
 (* -------------------------------------------------------------------------- *)
 (* --- Option                                                             --- *)

src/plugins/server/request.ml

@@ -162,14 +162,14 @@ let doc_input (type a) (input : a rq_input) =
   match input with
   | Pnone -> assert false
   | Pdata _ -> []
-  | Pfields fs -> [Syntax.fields ~title:"Input" (List.rev fs)]
+  | Pfields fs -> [Syntax.fields ~title:"Input Params" (List.rev fs)]
 
 (* json output syntax *)
 let doc_output (type b) (output : b rq_output) =
   match output with
   | Rnone -> assert false
   | Rdata _ -> []
-  | Rfields fs -> [Syntax.fields ~title:"Output" (List.rev fs)]
+  | Rfields fs -> [Syntax.fields ~title:"Output Params" (List.rev fs)]
 
 (* -------------------------------------------------------------------------- *)
 (* --- Multi-Parameters Requests                                          --- *)
@@ -339,16 +339,13 @@ let register_sig (type a b) (s : (a,b) signature) (process : rq -> a -> b) =
   let skind = Main.string_of_kind s.kind in
   let title =  Printf.sprintf "`%s` %s" skind s.name in
   let index = [ Printf.sprintf "%s (`%s`)" s.name skind ] in
-  let header = [ plain "Input", Center; plain "Output", Center] in
-  let content =
-    [[ Syntax.text @@ sy_input s.input ;
-       Syntax.text @@ sy_output s.output ]]
-  in
-  let synopsis = Table { caption=None ; header; content } in
+  let input =
+    Syntax.define (plain "Input") (Syntax.text @@ sy_input s.input) in
+  let output =
+    Syntax.define (plain "Output") (Syntax.text @@ sy_output s.output) in
   let description =
-    [ Block [Text s.descr ] ; synopsis ; Block s.details] @
-    doc_input s.input @
-    doc_output s.output
+    Block ( Text s.descr :: input :: output :: s.details ) ::
+    ( doc_input s.input @ doc_output s.output )
   in
   let _ =
     Doc.publish ~page:s.page ~name:s.name ~title ~index description []

src/plugins/server/syntax.ml

@@ -60,6 +60,9 @@ let text { text } = text
 let protect a =
   if a.atomic then a.text else Markdown.(plain "(" @ a.text @ plain ")")
 
+let define left right =
+  Markdown.(Block_quote [Block[Text ( left @ plain ":=" @ right )]])
+
 let publish ~page ~name ~descr ~synopsis ?(details = []) () =
   check_name name ;
   check_page page name ;
@@ -68,15 +71,16 @@ let publish ~page ~name ~descr ~synopsis ?(details = []) () =
   let index = [ Printf.sprintf "%s (`DATA`)" name ] in
   let dref = Doc.href page id in
   let dlink = Markdown.href ~text:(Markdown.emph name) dref in
-  let syntax = Markdown.(glue [
-      plain "<" ; dlink ; plain ">" ; plain ":=" ; synopsis.text ]) in
-  let content = Markdown.(Block ( text descr @ text syntax ) :: details) in
+  let data = Markdown.(plain "<" @ dlink @ plain ">") in
+  let content = Markdown.(Block(
+      [ Text descr ; define data synopsis.text ]
+    )) :: details in
   let _href = Doc.publish ~page ~name:id ~title ~index content [] in
   atom dlink
 
 (* -------------------------------------------------------------------------- *)
 
-let unit = atom @@ Markdown.plain "-"
+let unit = atom @@ Markdown.code "null"
 let any = atom @@ Markdown.emph "any"
 let int = atom @@ Markdown.emph "int"
 let ident = atom @@ Markdown.emph "ident"
@@ -86,7 +90,7 @@ let boolean = atom @@ Markdown.emph "boolean"
 let data name dref = atom @@ Markdown.href ~text:(Markdown.emph name) dref
 
 let escaped name =
-  Markdown.code (Printf.sprintf "'%s'" @@ String.escaped name)
+  Markdown.code (Printf.sprintf "\"%s\"" @@ String.escaped name)
 
 let tag name = atom @@ escaped name
 let array a = atom @@ Markdown.(code "[" @ protect a @ code  ", … ]")
@@ -146,7 +150,7 @@ let fields ?(title="Field") (fds : field list) =
     plain "Format", Center;
     plain "Description", Left
   ] in
-  let row f = [ code f.fd_name ; f.fd_syntax.text ; f.fd_descr ] in
+  let row f = [ escaped f.fd_name ; f.fd_syntax.text ; f.fd_descr ] in
   Markdown.Table {
     caption = None ; header ; content = List.map row fds ;
   }

src/plugins/server/syntax.mli

@@ -57,6 +57,9 @@ type tag = {
   tag_descr : Markdown.text ;
 }
 
+(** Syntactic definition: LEFT := RIGHT *)
+val define : Markdown.text -> Markdown.text -> Markdown.block_element
+
 (** Builds a table with tags description.
     The [~title] is applied to the tag name column
     (shall be capitalized, defaults to ["Tag"]). *)