Skip to content

Commit da7d723

Browse files
felixmulderfelixmulder
authored
Merge pull request #1939 from dotty-staging/topic/dottydoc-html-enhancements
[doc] html enhancements
2 parents b71acb9 + 96126c7 commit da7d723

File tree

7 files changed

+165
-17
lines changed

7 files changed

+165
-17
lines changed

‎doc-tool/resources/_layouts/api-page.html

Lines changed: 82 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@
1010

1111
<div id="entity-container">
1212
<div id="entity-title">
13+
<span id="entity-annotations">
14+
{% for annot in entity.annotations %}@{{ annot | split: '.' | last }} {% endfor %}
15+
</span>
1316
<span id="entity-modifiers">
1417
{{ entity.modifiers | join: " " }}
1518
</span>
@@ -19,6 +22,33 @@
1922
<span id="entity-name">
2023
{{ entity.name }}
2124
</span>
25+
{% if entity.typeParams.size > 0 %}
26+
<span id="entity-type-params">
27+
<span class="no-left">[</span>
28+
{% for param in entity.typeParams %}
29+
<span class="no-left">
30+
{% if forloop.last %}
31+
{{ param }}
32+
{% else %}
33+
{{ param }},
34+
{% endif %}
35+
</span>
36+
{% endfor %}
37+
<span class="no-left">]</span>
38+
</span>
39+
{% endif %}
40+
{% if entity.superTypes.size > 0 %}
41+
<div id="super-types">
42+
{% for super in entity.superTypes %}
43+
{% if forloop.first %}
44+
<span class="keyword">extends</span>
45+
{% else %}
46+
<span class="keyword">with</span>
47+
{% endif %}
48+
<span class="entity-super-type">{% renderLink super %}</span>
49+
{% endfor %}
50+
</div>
51+
{% endif %}
2252
</div>
2353

2454
{% if entity.comment.body %}
@@ -27,12 +57,45 @@
2757
</div>
2858
{% endif %}
2959

30-
<h1 class="section {% if entity.hasVisibleMembers == false %}empty{% endif %}">Members</h1>
60+
<h1 class="section {% if entity.constructors == null or entity.constructors.size == 0 %}empty{% endif %}">
61+
Constructors
62+
</h1>
63+
64+
<div id="entity-constructors" class="entity-section {% if entity.constructors == null or entity.constructors.size == 0 %}empty{% endif %}">
65+
{% for constructor in entity.constructors %}
66+
{% for plist in constructor %}
67+
<div class="member">
68+
<div class="member-title">
69+
<span class="member-name">{{ entity.name }}</span>
70+
<span class="no-left">(</span>
71+
{% if plist.isImplicit %}
72+
<span class="no-left keyword">implicit</span>
73+
{% endif %}
74+
{% for namedRef in plist.list %}
75+
<span class="{% if forloop.first %}no-left{% endif %}">
76+
{{ namedRef.title }}:{% if namedRef.isByName %} =&gt;{% endif %}
77+
</span>
78+
{% renderRef namedRef.ref %}
79+
{% if forloop.last != true %}
80+
<span class="no-left">, </span>
81+
{% endif %}
82+
{% endfor %}
83+
<span class="no-left">)</span>
84+
</div>
85+
</div>
86+
{% endfor %}
87+
{% endfor %}
88+
</div>
89+
90+
<h1 class="section {% if entity.hasVisibleMembers == false %}empty{% endif %}">
91+
Members
92+
</h1>
3193

3294
<div id="entity-members" class="entity-section {% if entity.hasVisibleMembers == false %}empty{% endif %}">
3395
{% for member in entity.members %}
3496
<div id="{{ member.signature }}" class="member {% if member.isPrivate %}private{% elsif member.isProtected %}protected{% endif %}">
3597
<div class="member-title">
98+
<span class="expand-button" onclick="toggleMemberBody(this, '{{ member.signature }}');">[+]</span>
3699
<span class="member-annotations">
37100
{% for annot in member.annotations %}@{{ annot | split: '.' | last }} {% endfor %}
38101
</span>
@@ -79,13 +142,29 @@ <h1 class="section {% if entity.hasVisibleMembers == false %}empty{% endif %}">M
79142
{% endif %}
80143

81144
{% if member.returnValue %}
82-
<span class="no-left">: {{ member.returnValue.title }}</span>
145+
<span class="no-left">: {% renderRef member.returnValue %}</span>
83146
{% endif %}
84147
</div><!-- end member-title -->
85148

86149
<div class="member-body">
87-
{{ member.comment.short }}
150+
<div class="member-body-short" id="short-body-{{ member.signature }}">
151+
{{ member.comment.short }}
152+
</div>
153+
<div class="member-body-long" id ="long-body-{{ member.signature }}">
154+
{{ member.comment.body }}
155+
</div>
88156
</div>
157+
<script>
158+
function toggleMemberBody(span, sig) {
159+
var shortBody = document.getElementById("short-body-" + sig);
160+
var longBody = document.getElementById("long-body-" + sig);
161+
162+
shortBody.classList.toggle("toggled")
163+
longBody.classList.toggle("toggled")
164+
165+
span.innerHTML = (span.innerHTML == "[+]") ? "[-]" : "[+]";
166+
}
167+
</script>
89168
</div><!-- end member -->
90169
{% endfor %}
91170
</div>

‎doc-tool/resources/css/api-page.css

Lines changed: 64 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,39 @@ div#entity-title {
1414
font-size: 2.5rem;
1515
}
1616

17+
div#entity-title > span#entity-annotations,
1718
div#entity-title > span#entity-modifiers,
1819
div#entity-title > span#entity-kind {
1920
font-weight: 100;
2021
}
2122

23+
div#entity-title > div#super-types > span.keyword {
24+
font-weight: 100;
25+
}
26+
27+
div#entity-title > div#super-types > span.keyword,
28+
div#entity-title > div#super-types > span.entity-super-type {
29+
font-size: 25px;
30+
}
31+
32+
div#entity-title > div#super-types> span.entity-super-type > a,
33+
div#entity-title > div#super-types> span.entity-super-type > a:focus {
34+
text-decoration: none;
35+
color: #34495e;
36+
}
37+
38+
div#entity-title > div#super-types> span.entity-super-type > a:hover {
39+
text-decoration: underline;
40+
}
41+
42+
div#entity-title span.no-left {
43+
margin-left: -9px;
44+
}
45+
46+
div#entity-title span.no-right {
47+
margin-right: -9px;
48+
}
49+
2250
div#entity-body table > tbody > tr > td {
2351
padding: 10px;
2452
}
@@ -42,44 +70,70 @@ h1.section {
4270
display: none;
4371
}
4472

45-
div#entity-members > div.member.protected {
73+
div.entity-section > div.member.protected {
4674
display: none;
4775
}
4876

49-
div#entity-members > div.member.private {
77+
div.entity-section > div.member.private {
5078
display: none;
5179
}
5280

53-
div#entity-members > div.member {
81+
div.entity-section > div.member {
5482
margin-bottom: 30px;
5583
}
5684

57-
div#entity-members > div.member:last-child {
85+
div.entity-section > div.member:last-child {
5886
margin-bottom: 0px;
5987
}
6088

61-
div#entity-members > div.member > div.member-title {
89+
div.entity-section > div.member > div.member-title {
6290
font-family: "Source Code Pro", sans-serif;
6391
}
6492

65-
div#entity-members > div.member > div.member-title > span.member-name {
93+
div.entity-section > div.member > div.member-title > span.member-name {
6694
color: #458;
6795
font-weight: 600;
6896
}
6997

70-
div#entity-members > div.member > div.member-title > span.member-name.implicitly-added {
98+
div.entity-section > div.member > div.member-title > span.member-name.implicitly-added {
7199
color: #019875;
72100
}
73101

74-
div#entity-members > div.member > div.member-title span.keyword {
102+
div.entity-section > div.member > div.member-title span.keyword {
75103
font-weight: 600;
76104
margin-right: 11px;
77105
}
78106

79-
div#entity-members > div.member > div.member-title span.no-left {
107+
div.entity-section > div.member > div.member-title span.no-left {
80108
margin-left: -11px;
81109
}
82110

83-
div#entity-members > div.member > div.member-title span.no-right {
111+
div.entity-section > div.member > div.member-title span.no-right {
84112
margin-right: -11px;
85113
}
114+
115+
div.entity-section > div.member > div.member-title > span.expand-button {
116+
color: rgba(167, 161, 161, 0.5);
117+
}
118+
119+
div.entity-section > div.member > div.member-title > span.expand-button:hover {
120+
color: rgb(167, 161, 161);
121+
cursor: pointer;
122+
user-select: none;
123+
}
124+
125+
div.entity-section > div.member > div.member-body {
126+
margin: 5px 0 0 39px;
127+
}
128+
129+
div.entity-section > div.member > div.member-body > div.member-body-short.toggled {
130+
display: none;
131+
}
132+
133+
div.entity-section > div.member > div.member-body > div.member-body-long {
134+
display: none;
135+
}
136+
137+
div.entity-section > div.member > div.member-body > div.member-body-long.toggled {
138+
display: block;
139+
}

‎doc-tool/src/dotty/tools/dottydoc/core/DocstringPhase.scala

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,4 +63,8 @@ class DocstringPhase extends DocMiniPhase with CommentParser with CommentCleaner
6363
override def transformVal(implicit ctx: Context) = { case ent: ValImpl =>
6464
ent.copy(comment = parsedComment(ent))
6565
}
66+
67+
override def transformTypeAlias(implicit ctx: Context) = { case ent: TypeAliasImpl =>
68+
ent.copy(comment = parsedComment(ent))
69+
}
6670
}

‎doc-tool/src/dotty/tools/dottydoc/core/TypeLinkingPhases.scala

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,14 @@ class LinkReturnTypes extends DocMiniPhase with TypeLinker {
2626
val returnValue = linkReference(vl, vl.returnValue, ctx.docbase.packages)
2727
vl.copy(returnValue = returnValue)
2828
}
29+
30+
override def transformTypeAlias(implicit ctx: Context) = { case ta: TypeAliasImpl =>
31+
ta.alias.map { alias =>
32+
val linkedAlias = linkReference(ta, alias, ctx.docbase.packages)
33+
ta.copy(alias = Some(linkedAlias))
34+
}
35+
.getOrElse(ta)
36+
}
2937
}
3038

3139
class LinkParamListTypes extends DocMiniPhase with TypeLinker {

‎doc-tool/src/dotty/tools/dottydoc/model/JavaConverters.scala

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ object JavaConverters {
7070
"typeParams" -> ent.typeParams.asJava,
7171
"superTypes" -> ent.superTypes.map(_.asJava).asJava,
7272
"comment" -> ent.comment.map(_.asJava).asJava,
73+
"constructors" -> ent.constructors.map(_.map(_.asJava).asJava).asJava,
7374
"isPrivate" -> ent.isPrivate,
7475
"isProtected" -> ent.isProtected,
7576
"hasVisibleMembers" -> ent.hasVisibleMembers,
@@ -90,6 +91,7 @@ object JavaConverters {
9091
"typeParams" -> ent.typeParams.asJava,
9192
"superTypes" -> ent.superTypes.map(_.asJava).asJava,
9293
"comment" -> ent.comment.map(_.asJava).asJava,
94+
"constructors" -> ent.constructors.map(_.map(_.asJava).asJava).asJava,
9395
"isPrivate" -> ent.isPrivate,
9496
"isProtected" -> ent.isProtected,
9597
"hasVisibleMembers" -> ent.hasVisibleMembers,

‎doc-tool/src/dotty/tools/dottydoc/staticsite/MarkdownLinkVisitor.scala

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,10 @@ object MarkdownLinkVisitor {
1414
new VisitHandler(classOf[Link], new Visitor[Link] with MemberLookup {
1515
override def visit(node: Link): Unit = {
1616
val url = node.getUrl
17-
if (EntityLink.unapplySeq(url.toString).isDefined) {
17+
if (url.endsWith(".md")) node.setUrl {
18+
url.subSequence(0, url.lastIndexOf('.')).append(".html")
19+
}
20+
else if (EntityLink.unapplySeq(url.toString).isDefined) {
1821
lookup(NonEntity, docs, url.toString).foreach { ent =>
1922
val (path, suffix) = ent match {
2023
case ent: Val => (ent.path.dropRight(1), ".html#" + ent.signature)
@@ -32,9 +35,6 @@ object MarkdownLinkVisitor {
3235
}
3336
}
3437
}
35-
else if (url.endsWith(".md")) node.setUrl {
36-
url.subSequence(0, url.lastIndexOf('.')).append(".html")
37-
}
3838
}
3939
})
4040
))

‎doc-tool/src/dotty/tools/dottydoc/staticsite/Template.scala

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ case class LiquidTemplate(path: String, content: SourceFile) extends Template wi
8787
Template.parse(show, JEKYLL)
8888
.`with`(ResourceInclude(params, includes))
8989
.`with`(RenderReference(params))
90+
.`with`(RenderLink(params))
9091
.`with`(RenderTitle(params))
9192
.`with`(Docstring(params))
9293
.render(toJavaMap(params))

0 commit comments

Comments
 (0)