Skip to content

Improve and simplify the layout for datatypes #673

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Improve and simplify the layout for datatypes #673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9c40377
Use lists instead of tables for types.
Drup Mar 12, 2021
f0ca0b5
Inline attached comments when they are composed of a single paragraph.
Drup Mar 12, 2021
d9564f5
Avoid overriding between different set of CSS classes.
Drup Mar 12, 2021
43e0d9a
Promote tests.
Drup Mar 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 43 additions & 34 deletions src/html/generator.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,12 @@ let mk_anchor_link id =

let mk_anchor anchor =
match anchor with
| None -> ([], [])
| None -> ([], [], [])
| Some { Odoc_document.Url.Anchor.anchor; _ } ->
let link = mk_anchor_link anchor in
let attrib = [ Html.a_id anchor; Html.a_class [ "anchored" ] ] in
(attrib, link)
let extra_attr = [ Html.a_id anchor ] in
let extra_class = [ "anchored" ] in
(extra_attr, extra_class, link)

let class_ (l : Class.t) = if l = [] then [] else [ Html.a_class l ]

Expand Down Expand Up @@ -193,6 +194,14 @@ let rec block ~resolve (l : Block.t) : flow Html.elt list =
in
Utils.list_concat_map l ~f:one

let classify_comment ~resolve (b : Block.t) = match b with
| [] ->
`Empty
| [ {desc = Inline i | Paragraph i; attr} ] ->
`Inline (attr, inline ~resolve i)
| _ ->
`Block (block ~resolve b)

(* This coercion is actually sound, but is not currently accepted by Tyxml.
See https://github.com/ocsigen/tyxml/pull/265 for details
Can be replaced by a simple type coercion once this is fixed
Expand All @@ -204,14 +213,34 @@ let div : ([< Html_types.div_attrib ], [< item ], [> Html_types.div ]) Html.star
=
Html.Unsafe.node "div"

let spec_class = function [] -> [] | attr -> class_ ("spec" :: attr)
let spec_class attr = class_ ("spec" :: attr)

let spec_doc_div ~resolve = function
| [] -> []
| docs ->
let a = [ Html.a_class [ "spec-doc" ] ] in
[ div ~a (flow_to_item @@ block ~resolve docs) ]

let attached_doc ~resolve markers doc =
let opening, closing = markers in
let delim s =
[Html.span ~a:(class_ [ "comment-delim" ]) [Html.txt s]]
in
match classify_comment ~resolve doc with
| `Empty -> []
| `Inline (attr, i) ->
[ Html.span ~a:(class_ ("def-doc" :: attr)) (
delim opening
@ i
@ delim closing
)]
| `Block b ->
[ Html.div ~a:(class_ [ "def-doc" ]) (
delim opening
@ b
@ delim closing
)]

let rec documentedSrc ~resolve (t : DocumentedSrc.t) : item Html.elt list =
let open DocumentedSrc in
let take_code l =
Expand Down Expand Up @@ -245,33 +274,13 @@ let rec documentedSrc ~resolve (t : DocumentedSrc.t) : item Html.elt list =
| `D code -> (inline ~resolve code :> item Html.elt list)
| `N n -> to_html n
in
let doc =
match doc with
| [] -> []
| doc ->
let opening, closing = markers in
[
Html.td
~a:(class_ [ "def-doc" ])
(Html.span
~a:(class_ [ "comment-delim" ])
[ Html.txt opening ]
:: block ~resolve doc
@ [
Html.span
~a:(class_ [ "comment-delim" ])
[ Html.txt closing ];
]);
]
in
let a, link = mk_anchor anchor in
let content =
let c = link @ content in
Html.td ~a:(class_ attrs) (c :> any Html.elt list)
in
Html.tr ~a (content :: doc)
let doc = attached_doc ~resolve markers doc in
let extra_attr, extra_class, link = mk_anchor anchor in
let content = (content :> any Html.elt list) in
Html.li ~a:(extra_attr @ class_ (attrs @ extra_class))
(link @ content @ doc)
in
Html.table (List.map one l) :: to_html rest
Html.ol (List.map one l) :: to_html rest
in
to_html t

Expand Down Expand Up @@ -303,8 +312,8 @@ and items ~resolve l : item Html.elt list =
let details ~open' =
let open' = if open' then [ Html.a_open () ] else [] in
let summary =
let anchor_attrib, anchor_link = mk_anchor anchor in
let a = spec_class attr @ anchor_attrib in
let extra_attr, extra_class, anchor_link = mk_anchor anchor in
let a = spec_class (attr @ extra_class) @ extra_attr in
Html.summary ~a @@ anchor_link @ source (inline ~resolve) summary
in
[ Html.details ~a:open' summary included_html ]
Expand All @@ -320,8 +329,8 @@ and items ~resolve l : item Html.elt list =
in
(continue_with [@tailcall]) rest inc
| Declaration { Item.attr; anchor; content; doc } :: rest ->
let anchor_attrib, anchor_link = mk_anchor anchor in
let a = spec_class attr @ anchor_attrib in
let extra_attr, extra_class, anchor_link = mk_anchor anchor in
let a = spec_class (attr @ extra_class) @ extra_attr in
let content = anchor_link @ documentedSrc ~resolve content in
let spec =
let doc = spec_doc_div ~resolve doc in
Expand Down
4 changes: 2 additions & 2 deletions test/html/expect/test_package+ml/Bugs_post_406/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,12 @@ <h1>
</header>
<div class="odoc-content">
<div class="odoc-spec">
<div class="spec class-type" id="class-type-let_open">
<div class="spec class-type anchored" id="class-type-let_open">
<a href="#class-type-let_open" class="anchor"></a><code><span><span class="keyword">class</span> <span class="keyword">type</span> </span><span><a href="class-type-let_open/index.html">let_open</a></span><span> = <span class="keyword">object</span> ... <span class="keyword">end</span></span></code>
</div>
</div>
<div class="odoc-spec">
<div class="spec class" id="class-let_open'">
<div class="spec class anchored" id="class-let_open'">
<a href="#class-let_open'" class="anchor"></a><code><span><span class="keyword">class</span> </span><span><a href="class-let_open'/index.html">let_open'</a></span><span> : <span class="keyword">object</span> ... <span class="keyword">end</span></span></code>
</div>
</div>
Expand Down
82 changes: 28 additions & 54 deletions test/html/expect/test_package+ml/Labels/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,12 @@ <h2 id="L2">
<a href="#L2" class="anchor"></a>Attached to nothing
</h2>
<div class="odoc-spec">
<div class="spec module" id="module-A">
<div class="spec module anchored" id="module-A">
<a href="#module-A" class="anchor"></a><code><span><span class="keyword">module</span> </span><span><a href="A/index.html">A</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code>
</div>
</div>
<div class="odoc-spec">
<div class="spec type" id="type-t">
<div class="spec type anchored" id="type-t">
<a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> t</span></code>
</div>
<div class="spec-doc">
Expand All @@ -55,7 +55,7 @@ <h2 id="L2">
</div>
</div>
<div class="odoc-spec">
<div class="spec value" id="val-f">
<div class="spec value anchored" id="val-f">
<a href="#val-f" class="anchor"></a><code><span><span class="keyword">val</span> f : <a href="#type-t">t</a></span></code>
</div>
<div class="spec-doc">
Expand All @@ -65,7 +65,7 @@ <h2 id="L2">
</div>
</div>
<div class="odoc-spec">
<div class="spec value external" id="val-e">
<div class="spec value external anchored" id="val-e">
<a href="#val-e" class="anchor"></a><code><span><span class="keyword">val</span> e : <span>unit <span class="arrow">-&gt;</span></span> <a href="#type-t">t</a></span></code>
</div>
<div class="spec-doc">
Expand All @@ -75,22 +75,22 @@ <h2 id="L2">
</div>
</div>
<div class="odoc-spec">
<div class="spec module-type" id="module-type-S">
<div class="spec module-type anchored" id="module-type-S">
<a href="#module-type-S" class="anchor"></a><code><span><span class="keyword">module</span> <span class="keyword">type</span> </span><span><a href="module-type-S/index.html">S</a></span><span> = <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code>
</div>
</div>
<div class="odoc-spec">
<div class="spec class" id="class-c">
<div class="spec class anchored" id="class-c">
<a href="#class-c" class="anchor"></a><code><span><span class="keyword">class</span> </span><span><a href="class-c/index.html">c</a></span><span> : <span class="keyword">object</span> ... <span class="keyword">end</span></span></code>
</div>
</div>
<div class="odoc-spec">
<div class="spec class-type" id="class-type-cs">
<div class="spec class-type anchored" id="class-type-cs">
<a href="#class-type-cs" class="anchor"></a><code><span><span class="keyword">class</span> <span class="keyword">type</span> </span><span><a href="class-type-cs/index.html">cs</a></span><span> = <span class="keyword">object</span> ... <span class="keyword">end</span></span></code>
</div>
</div>
<div class="odoc-spec">
<div class="spec exception" id="exception-E">
<div class="spec exception anchored" id="exception-E">
<a href="#exception-E" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">E</span></span></code>
</div>
<div class="spec-doc">
Expand All @@ -100,22 +100,18 @@ <h2 id="L2">
</div>
</div>
<div class="odoc-spec">
<div class="spec type" id="type-x">
<div class="spec type anchored" id="type-x">
<a href="#type-x" class="anchor"></a><code><span><span class="keyword">type</span> x</span><span> = </span><span>..</span></code>
</div>
</div>
<div class="odoc-spec">
<div class="spec type extension">
<code><span><span class="keyword">type</span> <a href="#type-x">x</a> += </span></code>
<table>
<tbody>
<tr id="extension-X" class="anchored">
<td class="def extension">
<a href="#extension-X" class="anchor"></a><code><span>| </span><span><span class="extension">X</span></span></code>
</td>
</tr>
</tbody>
</table>
<ol>
<li id="extension-X" class="def extension anchored">
<a href="#extension-X" class="anchor"></a><code><span>| </span><span><span class="extension">X</span></span></code>
</li>
</ol>
</div>
<div class="spec-doc">
<p>
Expand All @@ -124,7 +120,7 @@ <h2 id="L2">
</div>
</div>
<div class="odoc-spec">
<div class="spec module-substitution" id="module-S">
<div class="spec module-substitution anchored" id="module-S">
<a href="#module-S" class="anchor"></a><code><span><span class="keyword">module</span> S := <a href="A/index.html">A</a></span></code>
</div>
<div class="spec-doc">
Expand All @@ -134,7 +130,7 @@ <h2 id="L2">
</div>
</div>
<div class="odoc-spec">
<div class="spec type subst" id="type-s">
<div class="spec type subst anchored" id="type-s">
<a href="#type-s" class="anchor"></a><code><span><span class="keyword">type</span> s</span><span> := <a href="#type-t">t</a></span></code>
</div>
<div class="spec-doc">
Expand All @@ -144,45 +140,23 @@ <h2 id="L2">
</div>
</div>
<div class="odoc-spec">
<div class="spec type" id="type-u">
<div class="spec type anchored" id="type-u">
<a href="#type-u" class="anchor"></a><code><span><span class="keyword">type</span> u</span><span> = </span></code>
<table>
<tbody>
<tr id="type-u.A'" class="anchored">
<td class="def variant constructor">
<a href="#type-u.A'" class="anchor"></a><code><span>| </span><span><span class="constructor">A'</span></span></code>
</td>
<td class="def-doc">
<span class="comment-delim">(*</span>
<p>
Attached to constructor
</p>
<span class="comment-delim">*)</span>
</td>
</tr>
</tbody>
</table>
<ol>
<li id="type-u.A'" class="def variant constructor anchored">
<a href="#type-u.A'" class="anchor"></a><code><span>| </span><span><span class="constructor">A'</span></span></code><span class="def-doc"><span class="comment-delim">(*</span>Attached to constructor<span class="comment-delim">*)</span></span>
</li>
</ol>
</div>
</div>
<div class="odoc-spec">
<div class="spec type" id="type-v">
<div class="spec type anchored" id="type-v">
<a href="#type-v" class="anchor"></a><code><span><span class="keyword">type</span> v</span><span> = </span><span>{</span></code>
<table>
<tbody>
<tr id="type-v.f" class="anchored">
<td class="def record field">
<a href="#type-v.f" class="anchor"></a><code><span>f : <a href="#type-t">t</a>;</span></code>
</td>
<td class="def-doc">
<span class="comment-delim">(*</span>
<p>
Attached to field
</p>
<span class="comment-delim">*)</span>
</td>
</tr>
</tbody>
</table>
<ol>
<li id="type-v.f" class="def record field anchored">
<a href="#type-v.f" class="anchor"></a><code><span>f : <a href="#type-t">t</a>;</span></code><span class="def-doc"><span class="comment-delim">(*</span>Attached to field<span class="comment-delim">*)</span></span>
</li>
</ol>
<code><span>}</span></code>
</div>
</div>
Expand Down
2 changes: 1 addition & 1 deletion test/html/expect/test_package+ml/Markup/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,7 @@ <h2 id="tags">
</li>
</ul>
<div class="odoc-spec">
<div class="spec value" id="val-foo">
<div class="spec value anchored" id="val-foo">
<a href="#val-foo" class="anchor"></a><code><span><span class="keyword">val</span> foo : unit</span></code>
</div>
<div class="spec-doc">
Expand Down
Loading