Skip to content

[doc] html enhancements #1939

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

Merged
merged 6 commits into from
Feb 3, 2017
Merged

[doc] html enhancements #1939

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b072fd6
Add expansion of docstrings
felixmulder Feb 3, 2017
eff150f
Add type parameters to entity title and render return type correctly
felixmulder Feb 3, 2017
cf068d4
Add supertypes and annotations to entity title
felixmulder Feb 3, 2017
79c17ae
Make sure `TypeAlias`es get proper docstrings and linked aliases
felixmulder Feb 3, 2017
5995dd3
Add constructors to docs
felixmulder Feb 3, 2017
96126c7
fix #1940 - broken .md links
felixmulder Feb 3, 2017
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
85 changes: 82 additions & 3 deletions doc-tool/resources/_layouts/api-page.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@

<div id="entity-container">
<div id="entity-title">
<span id="entity-annotations">
{% for annot in entity.annotations %}@{{ annot | split: '.' | last }} {% endfor %}
</span>
<span id="entity-modifiers">
{{ entity.modifiers | join: " " }}
</span>
Expand All @@ -19,6 +22,33 @@
<span id="entity-name">
{{ entity.name }}
</span>
{% if entity.typeParams.size > 0 %}
<span id="entity-type-params">
<span class="no-left">[</span>
{% for param in entity.typeParams %}
<span class="no-left">
{% if forloop.last %}
{{ param }}
{% else %}
{{ param }},
{% endif %}
</span>
{% endfor %}
<span class="no-left">]</span>
</span>
{% endif %}
{% if entity.superTypes.size > 0 %}
<div id="super-types">
{% for super in entity.superTypes %}
{% if forloop.first %}
<span class="keyword">extends</span>
{% else %}
<span class="keyword">with</span>
{% endif %}
<span class="entity-super-type">{% renderLink super %}</span>
{% endfor %}
</div>
{% endif %}
</div>

{% if entity.comment.body %}
Expand All @@ -27,12 +57,45 @@
</div>
{% endif %}

<h1 class="section {% if entity.hasVisibleMembers == false %}empty{% endif %}">Members</h1>
<h1 class="section {% if entity.constructors == null or entity.constructors.size == 0 %}empty{% endif %}">
Constructors
</h1>

<div id="entity-constructors" class="entity-section {% if entity.constructors == null or entity.constructors.size == 0 %}empty{% endif %}">
{% for constructor in entity.constructors %}
{% for plist in constructor %}
<div class="member">
<div class="member-title">
<span class="member-name">{{ entity.name }}</span>
<span class="no-left">(</span>
{% if plist.isImplicit %}
<span class="no-left keyword">implicit</span>
{% endif %}
{% for namedRef in plist.list %}
<span class="{% if forloop.first %}no-left{% endif %}">
{{ namedRef.title }}:{% if namedRef.isByName %} =&gt;{% endif %}
</span>
{% renderRef namedRef.ref %}
{% if forloop.last != true %}
<span class="no-left">, </span>
{% endif %}
{% endfor %}
<span class="no-left">)</span>
</div>
</div>
{% endfor %}
{% endfor %}
</div>

<h1 class="section {% if entity.hasVisibleMembers == false %}empty{% endif %}">
Members
</h1>

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

{% if member.returnValue %}
<span class="no-left">: {{ member.returnValue.title }}</span>
<span class="no-left">: {% renderRef member.returnValue %}</span>
{% endif %}
</div><!-- end member-title -->

<div class="member-body">
{{ member.comment.short }}
<div class="member-body-short" id="short-body-{{ member.signature }}">
{{ member.comment.short }}
</div>
<div class="member-body-long" id ="long-body-{{ member.signature }}">
{{ member.comment.body }}
</div>
</div>
<script>
function toggleMemberBody(span, sig) {
var shortBody = document.getElementById("short-body-" + sig);
var longBody = document.getElementById("long-body-" + sig);

shortBody.classList.toggle("toggled")
longBody.classList.toggle("toggled")

span.innerHTML = (span.innerHTML == "[+]") ? "[-]" : "[+]";
}
</script>
</div><!-- end member -->
{% endfor %}
</div>
Expand Down
74 changes: 64 additions & 10 deletions doc-tool/resources/css/api-page.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,39 @@ div#entity-title {
font-size: 2.5rem;
}

div#entity-title > span#entity-annotations,
div#entity-title > span#entity-modifiers,
div#entity-title > span#entity-kind {
font-weight: 100;
}

div#entity-title > div#super-types > span.keyword {
font-weight: 100;
}

div#entity-title > div#super-types > span.keyword,
div#entity-title > div#super-types > span.entity-super-type {
font-size: 25px;
}

div#entity-title > div#super-types> span.entity-super-type > a,
div#entity-title > div#super-types> span.entity-super-type > a:focus {
text-decoration: none;
color: #34495e;
}

div#entity-title > div#super-types> span.entity-super-type > a:hover {
text-decoration: underline;
}

div#entity-title span.no-left {
margin-left: -9px;
}

div#entity-title span.no-right {
margin-right: -9px;
}

div#entity-body table > tbody > tr > td {
padding: 10px;
}
Expand All @@ -42,44 +70,70 @@ h1.section {
display: none;
}

div#entity-members > div.member.protected {
div.entity-section > div.member.protected {
display: none;
}

div#entity-members > div.member.private {
div.entity-section > div.member.private {
display: none;
}

div#entity-members > div.member {
div.entity-section > div.member {
margin-bottom: 30px;
}

div#entity-members > div.member:last-child {
div.entity-section > div.member:last-child {
margin-bottom: 0px;
}

div#entity-members > div.member > div.member-title {
div.entity-section > div.member > div.member-title {
font-family: "Source Code Pro", sans-serif;
}

div#entity-members > div.member > div.member-title > span.member-name {
div.entity-section > div.member > div.member-title > span.member-name {
color: #458;
font-weight: 600;
}

div#entity-members > div.member > div.member-title > span.member-name.implicitly-added {
div.entity-section > div.member > div.member-title > span.member-name.implicitly-added {
color: #019875;
}

div#entity-members > div.member > div.member-title span.keyword {
div.entity-section > div.member > div.member-title span.keyword {
font-weight: 600;
margin-right: 11px;
}

div#entity-members > div.member > div.member-title span.no-left {
div.entity-section > div.member > div.member-title span.no-left {
margin-left: -11px;
}

div#entity-members > div.member > div.member-title span.no-right {
div.entity-section > div.member > div.member-title span.no-right {
margin-right: -11px;
}

div.entity-section > div.member > div.member-title > span.expand-button {
color: rgba(167, 161, 161, 0.5);
}

div.entity-section > div.member > div.member-title > span.expand-button:hover {
color: rgb(167, 161, 161);
cursor: pointer;
user-select: none;
}

div.entity-section > div.member > div.member-body {
margin: 5px 0 0 39px;
}

div.entity-section > div.member > div.member-body > div.member-body-short.toggled {
display: none;
}

div.entity-section > div.member > div.member-body > div.member-body-long {
display: none;
}

div.entity-section > div.member > div.member-body > div.member-body-long.toggled {
display: block;
}
4 changes: 4 additions & 0 deletions doc-tool/src/dotty/tools/dottydoc/core/DocstringPhase.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,8 @@ class DocstringPhase extends DocMiniPhase with CommentParser with CommentCleaner
override def transformVal(implicit ctx: Context) = { case ent: ValImpl =>
ent.copy(comment = parsedComment(ent))
}

override def transformTypeAlias(implicit ctx: Context) = { case ent: TypeAliasImpl =>
ent.copy(comment = parsedComment(ent))
}
}
8 changes: 8 additions & 0 deletions doc-tool/src/dotty/tools/dottydoc/core/TypeLinkingPhases.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,14 @@ class LinkReturnTypes extends DocMiniPhase with TypeLinker {
val returnValue = linkReference(vl, vl.returnValue, ctx.docbase.packages)
vl.copy(returnValue = returnValue)
}

override def transformTypeAlias(implicit ctx: Context) = { case ta: TypeAliasImpl =>
ta.alias.map { alias =>
val linkedAlias = linkReference(ta, alias, ctx.docbase.packages)
ta.copy(alias = Some(linkedAlias))
}
.getOrElse(ta)
}
}

class LinkParamListTypes extends DocMiniPhase with TypeLinker {
Expand Down
2 changes: 2 additions & 0 deletions doc-tool/src/dotty/tools/dottydoc/model/JavaConverters.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ object JavaConverters {
"typeParams" -> ent.typeParams.asJava,
"superTypes" -> ent.superTypes.map(_.asJava).asJava,
"comment" -> ent.comment.map(_.asJava).asJava,
"constructors" -> ent.constructors.map(_.map(_.asJava).asJava).asJava,
"isPrivate" -> ent.isPrivate,
"isProtected" -> ent.isProtected,
"hasVisibleMembers" -> ent.hasVisibleMembers,
Expand All @@ -90,6 +91,7 @@ object JavaConverters {
"typeParams" -> ent.typeParams.asJava,
"superTypes" -> ent.superTypes.map(_.asJava).asJava,
"comment" -> ent.comment.map(_.asJava).asJava,
"constructors" -> ent.constructors.map(_.map(_.asJava).asJava).asJava,
"isPrivate" -> ent.isPrivate,
"isProtected" -> ent.isProtected,
"hasVisibleMembers" -> ent.hasVisibleMembers,
Expand Down
8 changes: 4 additions & 4 deletions doc-tool/src/dotty/tools/dottydoc/staticsite/MarkdownLinkVisitor.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@ object MarkdownLinkVisitor {
new VisitHandler(classOf[Link], new Visitor[Link] with MemberLookup {
override def visit(node: Link): Unit = {
val url = node.getUrl
if (EntityLink.unapplySeq(url.toString).isDefined) {
if (url.endsWith(".md")) node.setUrl {
url.subSequence(0, url.lastIndexOf('.')).append(".html")
}
else if (EntityLink.unapplySeq(url.toString).isDefined) {
lookup(NonEntity, docs, url.toString).foreach { ent =>
val (path, suffix) = ent match {
case ent: Val => (ent.path.dropRight(1), ".html#" + ent.signature)
Expand All @@ -32,9 +35,6 @@ object MarkdownLinkVisitor {
}
}
}
else if (url.endsWith(".md")) node.setUrl {
url.subSequence(0, url.lastIndexOf('.')).append(".html")
}
}
})
))
Expand Down
1 change: 1 addition & 0 deletions doc-tool/src/dotty/tools/dottydoc/staticsite/Template.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ case class LiquidTemplate(path: String, content: SourceFile) extends Template wi
Template.parse(show, JEKYLL)
.`with`(ResourceInclude(params, includes))
.`with`(RenderReference(params))
.`with`(RenderLink(params))
.`with`(RenderTitle(params))
.`with`(Docstring(params))
.render(toJavaMap(params))
Expand Down