Print preamble for nested items (ocaml#194)

ryyppy · Oct 7, 2018 · a300e45 · a300e45
1 parent a7539dc
commit a300e45
Show file tree

Hide file tree

Showing 20 changed files with 342 additions and 192 deletions.
diff --git a/src/html/html_generator.ml b/src/html/html_generator.ml
@@ -168,7 +168,7 @@ module type Html_generator = sig
          item_to_id:('item -> string option)
       -> item_to_spec:('item -> string option)
       -> render_leaf_item:('item -> rendered_item * Comment.docs)
-      -> render_nested_article:('item -> rendered_item * Html_tree.t list)
+      -> render_nested_article:('item -> rendered_item * Comment.docs * Html_tree.t list)
       -> (_, 'item) tagged_item list
       -> rendered_item * toc * Html_tree.t list
 
@@ -228,19 +228,19 @@ module type Html_generator = sig
     val class_ :
          ?theme_uri:Html_tree.uri
       -> Lang.Class.t
-      -> Html_types.article_content Html.elt list * Html_tree.t list
+      -> rendered_item * Comment.docs * Html_tree.t list
 
     val class_type :
          ?theme_uri:Html_tree.uri
       -> Lang.ClassType.t
-      -> Html_types.article_content Html.elt list * Html_tree.t list
+      -> rendered_item * Comment.docs * Html_tree.t list
   end
 
   module Module : sig
     val signature :
          ?theme_uri:Html_tree.uri
       -> Lang.Signature.t
-      -> Html_types.div_content Html.elt list * toc * Html_tree.t list
+      -> rendered_item * toc * Html_tree.t list
   end
 end
 
@@ -842,7 +842,7 @@ sig
     item_to_id:('item -> string option) ->
     item_to_spec:('item -> string option) ->
     render_leaf_item:('item -> rendered_item * Comment.docs) ->
-    render_nested_article:('item -> rendered_item * Html_tree.t list) ->
+    render_nested_article:('item -> rendered_item * Comment.docs * Html_tree.t list) ->
     ((_, 'item) tagged_item) list ->
       rendered_item * toc * Html_tree.t list
 
@@ -988,7 +988,7 @@ struct
     item_to_id : 'item -> string option;
     item_to_spec : 'item -> string option;
     render_leaf_item : 'item -> rendered_item * Comment.docs;
-    render_nested_article : 'item -> rendered_item * Html_tree.t list;
+    render_nested_article : 'item -> rendered_item * Comment.docs * Html_tree.t list;
   }
 
   let finish_section state =
@@ -1032,14 +1032,25 @@ struct
           }
 
       | `Nested_article item ->
-        let html, subpages = state.render_nested_article item in
+        let html, maybe_docs, subpages = state.render_nested_article item in
         let html, maybe_id = add_anchor state.item_to_id item html in
         let a = add_spec state.item_to_spec item maybe_id in
-        section_items section_level {state with
-            input_items;
-            acc_html = (Html.article ~a html)::state.acc_html;
-            acc_subpages = state.acc_subpages @ subpages;
-          }
+        let html =
+          match maybe_docs with
+          | [] -> Html.div ~a html
+          | docs ->
+            let docs = Documentation.first_to_html docs in
+            let docs = (docs :> (Html_types.dd_content Html.elt) list) in
+            (* Temporary coercion until https://github.com/ocsigen/tyxml/pull/193
+               is released in TyXML; see also type [rendered_item]. *)
+            let html = List.map Html.Unsafe.coerce_elt html in
+            Html.dl [Html.dt ~a html; Html.dd docs]
+        in
+        section_items section_level { state with
+          input_items;
+          acc_html = html::state.acc_html;
+          acc_subpages = state.acc_subpages @ subpages;
+        }
 
       | `Comment `Stop ->
         let input_items = skip_everything_until_next_stop_comment input_items in
@@ -1186,11 +1197,11 @@ module Class :
 sig
   val class_ :
     ?theme_uri:Html_tree.uri -> Lang.Class.t ->
-      ((Html_types.article_content Html.elt) list) * (Html_tree.t list)
+      rendered_item * Comment.docs * Html_tree.t list
 
   val class_type :
     ?theme_uri:Html_tree.uri -> Lang.ClassType.t ->
-      ((Html_types.article_content Html.elt) list) * (Html_tree.t list)
+      rendered_item * Comment.docs * Html_tree.t list
 end =
 struct
   let class_signature_item_to_id : Lang.ClassSignature.item -> _ = function
@@ -1327,11 +1338,9 @@ struct
       Html.pcdata Syn.Type.annotation_separator ::
       cd
     in
-    let region =
-      [Html.code class_def_content]
-        (* ~doc:(relax_docs_type (Documentation.first_to_html t.doc)) *)
-    in
-    region, subtree
+    let region = [Html.code class_def_content] in
+    region, t.doc, subtree
+
 
   and class_type ?theme_uri (t : Model.Lang.ClassType.t) =
     let name = Paths.Identifier.name t.id in
@@ -1364,21 +1373,17 @@ struct
       Html.pcdata " = " ::
       expr
     in
-    let region =
-      [Html.code ctyp]
-        (* ~doc:(relax_docs_type (Documentation.first_to_html t.doc)) *)
-    in
-    region, subtree
+    let region = [Html.code ctyp] in
+    region, t.doc, subtree
 end
 open Class
 
 
 
 module Module :
 sig
-  val signature :
-    ?theme_uri:Html_tree.uri -> Lang.Signature.t ->
-      (Html_types.div_content Html.elt) list * toc * Html_tree.t list
+  val signature : ?theme_uri:Html_tree.uri -> Lang.Signature.t ->
+    rendered_item * toc * Html_tree.t list
 end =
 struct
   let signature_item_to_id : Lang.Signature.item -> _ = function
@@ -1520,7 +1525,7 @@ struct
 
   and module_
       : ?theme_uri:Html_tree.uri -> Model.Lang.Module.t ->
-          Html_types.article_content Html.elt list * Html_tree.t list
+          rendered_item * Comment.docs * Html_tree.t list
       = fun ?theme_uri t ->
     let modname = Paths.Identifier.name t.id in
     let md =
@@ -1556,12 +1561,11 @@ struct
         Html_tree.leave ();
         Html.a ~a:[ a_href ~kind:`Mod modname ] [Html.pcdata modname], [subtree]
     in
-    let md_def_content = Markup.keyword "module " :: modname :: md @ ( if Syn.Mod.close_tag_semicolon then [ Markup.keyword ";" ] else [] ) in
-    let region =
-      [Html.code md_def_content]
-        (* ~doc:(relax_docs_type (Documentation.first_to_html t.doc)) *)
-    in
-    region, subtree
+    let md_def_content =
+      Markup.keyword "module " :: modname :: md @
+      (if Syn.Mod.close_tag_semicolon then [Markup.keyword ";"] else []) in
+    let region = [Html.code md_def_content] in
+    region, t.doc, subtree
 
   and module_decl (base : Paths.Identifier.signature) md =
     begin match md with
@@ -1639,11 +1643,8 @@ struct
         @ ( if Syn.Mod.close_tag_semicolon then [ Markup.keyword ";" ] else [] )
       )
     in
-    let region =
-      [Html.code mty_def]
-        (* ~doc:(relax_docs_type (Documentation.first_to_html t.doc)) *)
-    in
-    region, subtree
+    let region = [Html.code mty_def] in
+    region, t.doc, subtree
 
   and mty
     : 'inner_row 'outer_row.
@@ -1765,6 +1766,7 @@ struct
           [Html.div ~a:[Html.a_class ["doc"]]
             (docs @ incl)])
     ],
+    [],
     tree
 end
 open Module

diff --git a/src/html/html_generator.mli b/src/html/html_generator.mli
@@ -140,7 +140,7 @@ module type Html_generator = sig
          item_to_id:('item -> string option)
       -> item_to_spec:('item -> string option)
       -> render_leaf_item:('item -> rendered_item * Comment.docs)
-      -> render_nested_article:('item -> rendered_item * Html_tree.t list)
+      -> render_nested_article:('item -> rendered_item * Comment.docs * Html_tree.t list)
       -> (_, 'item) tagged_item list
       -> rendered_item * toc * Html_tree.t list
 
@@ -200,12 +200,12 @@ module type Html_generator = sig
     val class_ :
          ?theme_uri:Html_tree.uri
       -> Lang.Class.t
-      -> Html_types.article_content Html.elt list * Html_tree.t list
+      -> rendered_item * Comment.docs * Html_tree.t list
 
     val class_type :
          ?theme_uri:Html_tree.uri
       -> Lang.ClassType.t
-      -> Html_types.article_content Html.elt list * Html_tree.t list
+      -> rendered_item * Comment.docs * Html_tree.t list
   end
 
   module Module : sig

diff --git a/test/html/cases/nested.mli b/test/html/cases/nested.mli
@@ -0,0 +1,35 @@
+
+(** This is module X.
+
+    Some additional comments. *)
+module X : sig
+  type t
+  (** Some type. *)
+
+  val x : t
+  (** The value of x. *)
+end
+
+
+
+(** This is module type Y.
+
+    Some additional comments. *)
+module type Y = sig
+  type t
+  (** Some type. *)
+
+  val y : t
+  (** The value of y. *)
+end
+
+
+(** This is class z.
+
+    Some additional comments. *)
+class z : object
+
+  method z : int
+  (** Some method. *)
+end
+
diff --git a/test/html/expect/test_package+custom_theme,ml/Include/index.html b/test/html/expect/test_package+custom_theme,ml/Include/index.html
@@ -21,10 +21,10 @@ <h1>
      Module <code>Include</code>
     </h1>
    </header>
-   <article class="spec module-type" id="module-type-Not_inlined">
+   <div class="spec module-type" id="module-type-Not_inlined">
     <a href="#module-type-Not_inlined" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-Not_inlined/index.html">Not_inlined</a> = <span class="keyword">sig</span> ... <span class="keyword">end</span></code>
-   </article>
-   <article>
+   </div>
+   <div>
     <div class="spec include">
      <div class="doc">
       <details open="open">
@@ -39,11 +39,11 @@ <h1>
       </details>
      </div>
     </div>
-   </article>
-   <article class="spec module-type" id="module-type-Inlined">
+   </div>
+   <div class="spec module-type" id="module-type-Inlined">
     <a href="#module-type-Inlined" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-Inlined/index.html">Inlined</a> = <span class="keyword">sig</span> ... <span class="keyword">end</span></code>
-   </article>
-   <article>
+   </div>
+   <div>
     <div class="spec include">
      <div class="doc">
       <dl>
@@ -53,11 +53,11 @@ <h1>
       </dl>
      </div>
     </div>
-   </article>
-   <article class="spec module-type" id="module-type-Not_inlined_and_closed">
+   </div>
+   <div class="spec module-type" id="module-type-Not_inlined_and_closed">
     <a href="#module-type-Not_inlined_and_closed" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-Not_inlined_and_closed/index.html">Not_inlined_and_closed</a> = <span class="keyword">sig</span> ... <span class="keyword">end</span></code>
-   </article>
-   <article>
+   </div>
+   <div>
     <div class="spec include">
      <div class="doc">
       <details>
@@ -72,11 +72,11 @@ <h1>
       </details>
      </div>
     </div>
-   </article>
-   <article class="spec module-type" id="module-type-Not_inlined_and_opened">
+   </div>
+   <div class="spec module-type" id="module-type-Not_inlined_and_opened">
     <a href="#module-type-Not_inlined_and_opened" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-Not_inlined_and_opened/index.html">Not_inlined_and_opened</a> = <span class="keyword">sig</span> ... <span class="keyword">end</span></code>
-   </article>
-   <article>
+   </div>
+   <div>
     <div class="spec include">
      <div class="doc">
       <details open="open">
@@ -91,7 +91,7 @@ <h1>
       </details>
      </div>
     </div>
-   </article>
+   </div>
   </div>
  </body>
 </html>
diff --git a/test/html/expect/test_package+custom_theme,ml/Module/index.html b/test/html/expect/test_package+custom_theme,ml/Module/index.html
@@ -34,44 +34,44 @@ <h1>
      </p>
     </dd>
    </dl>
-   <article class="spec module-type" id="module-type-S">
+   <div class="spec module-type" id="module-type-S">
     <a href="#module-type-S" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S/index.html">S</a> = <span class="keyword">sig</span> ... <span class="keyword">end</span></code>
-   </article>
-   <article class="spec module-type" id="module-type-S1">
+   </div>
+   <div class="spec module-type" id="module-type-S1">
     <a href="#module-type-S1" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S1/index.html">S1</a></code>
-   </article>
-   <article class="spec module-type" id="module-type-S2">
+   </div>
+   <div class="spec module-type" id="module-type-S2">
     <a href="#module-type-S2" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S2/index.html">S2</a> = <a href="index.html#module-type-S">S</a></code>
-   </article>
-   <article class="spec module-type" id="module-type-S3">
+   </div>
+   <div class="spec module-type" id="module-type-S3">
     <a href="#module-type-S3" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S3/index.html">S3</a> : <a href="index.html#module-type-S">S</a><span class="keyword"> with </span><span class="keyword">type </span><a href="module-type-S3/index.html#type-t">t</a><span class="keyword"> = </span>int<span class="keyword"> and </span><span class="keyword">type </span><a href="module-type-S3/index.html#type-u">u</a><span class="keyword"> = </span>string</code>
-   </article>
-   <article class="spec module-type" id="module-type-S4">
+   </div>
+   <div class="spec module-type" id="module-type-S4">
     <a href="#module-type-S4" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S4/index.html">S4</a> : <a href="index.html#module-type-S">S</a><span class="keyword"> with </span><span class="keyword">type </span><a href="module-type-S4/index.html#type-t">t</a> := int</code>
-   </article>
-   <article class="spec module-type" id="module-type-S5">
+   </div>
+   <div class="spec module-type" id="module-type-S5">
     <a href="#module-type-S5" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S5/index.html">S5</a> : <a href="index.html#module-type-S">S</a><span class="keyword"> with </span><span class="keyword">type </span>'a <a href="module-type-S5/index.html#type-v">v</a> := <span class="type-var">'a</span> list</code>
-   </article>
+   </div>
    <dl>
     <dt class="spec type" id="type-result">
      <a href="#type-result" class="anchor"></a><code><span class="keyword">type </span>('a, 'b) result</code>
     </dt>
    </dl>
-   <article class="spec module-type" id="module-type-S6">
+   <div class="spec module-type" id="module-type-S6">
     <a href="#module-type-S6" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S6/index.html">S6</a> : <a href="index.html#module-type-S">S</a><span class="keyword"> with </span><span class="keyword">type </span>('a, 'b) <a href="module-type-S6/index.html#type-w">w</a> := (<span class="type-var">'a</span>,&nbsp;<span class="type-var">'b</span>) <a href="index.html#type-result">result</a></code>
-   </article>
-   <article class="spec module" id="module-M'">
+   </div>
+   <div class="spec module" id="module-M'">
     <a href="#module-M'" class="anchor"></a><code><span class="keyword">module </span><a href="M'/index.html">M'</a> : <span class="keyword">sig</span> ... <span class="keyword">end</span></code>
-   </article>
-   <article class="spec module-type" id="module-type-S7">
+   </div>
+   <div class="spec module-type" id="module-type-S7">
     <a href="#module-type-S7" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S7/index.html">S7</a> : <a href="index.html#module-type-S">S</a><span class="keyword"> with </span><span class="keyword">module </span><a href="module-type-S7/M/index.html">M</a> = <a href="index.html#module-M'">M'</a></code>
-   </article>
-   <article class="spec module-type" id="module-type-S8">
+   </div>
+   <div class="spec module-type" id="module-type-S8">
     <a href="#module-type-S8" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S8/index.html">S8</a> : <a href="index.html#module-type-S">S</a><span class="keyword"> with </span><span class="keyword">module </span><a href="module-type-S8/M/index.html">M</a> := <a href="index.html#module-M'">M'</a></code>
-   </article>
-   <article class="spec module-type" id="module-type-S9">
+   </div>
+   <div class="spec module-type" id="module-type-S9">
     <a href="#module-type-S9" class="anchor"></a><code><span class="keyword">module type </span><a href="module-type-S9/index.html">S9</a> : <span class="keyword">module type of </span><a href="index.html#module-M'">M'</a></code>
-   </article>
+   </div>
   </div>
  </body>
 </html>
diff --git a/test/html/expect/test_package+ml/Class/index.html b/test/html/expect/test_package+ml/Class/index.html
@@ -21,9 +21,9 @@ <h1>
      Module <code>Class</code>
     </h1>
    </header>
-   <article class="spec class-type" id="class-type-empty">
+   <div class="spec class-type" id="class-type-empty">
     <a href="#class-type-empty" class="anchor"></a><code><span class="keyword">class type </span><a href="class-type-empty/index.html">empty</a> = <span class="keyword">object</span> ... <span class="keyword">end</span></code>
-   </article>
+   </div>
   </div>
  </body>
 </html>