waalge/aiken
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Parse and display documentation section headers.

Browse Source 
The idea is pretty simple, we'll just look for lines starting with Markdown heading sections, and render them in the documentation. They appear both in the sidebar, and within the generated docs themselves in between functions. This, coupled with the order preservation of the declaration in a module should make the generated docs significantly more elegant to organize and present.
This commit is contained in:
KtorZ
2024-08-22 15:08:21 +02:00
parent 0ff12b9246
commit 10c829edfa
4 changed files with 158 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
crates/aiken-project/templates/css/index.css
View File

@@ -290,11 +290,13 @@ p code {
/* Module doc */
.module-name > a,
.module-heading > a,
.module-member-kind > a {
color: inherit;
}
.module-name > a:hover,
.module-heading > a:hover,
.module-member-kind > a:hover {
text-decoration: none;
}
@@ -328,6 +330,7 @@ p code {
.sidebar h2 {
margin: 0;
color: var(--color-link-accent);
font-size: 1.75em;
}
.sidebar h3.modules-prefix {
@@ -407,6 +410,10 @@ body.drawer-open .label-closed {
.module-member-kind {
font-size: 2rem;
}
.module-heading,
.module-member-kind {
color: var(--color-text);
}
@@ -1113,3 +1120,29 @@ body.theme-dark {
.sidebar li[data-indent="1"]::before { padding-left: 1rem; }
.sidebar li[data-indent="2"]::before { padding-left: 2rem; }
.sidebar li[data-indent="3"]::before { padding-left: 3rem; }
.sidebar li[data-heading] {
font-weight: bold;
font-size: 1em;
color: var(--color-link-accent);
}
.sidebar li[data-heading="1"] {
margin-top: 1.5rem;
font-size: 1.4em;
}
.sidebar li[data-heading="2"] {
margin-top: 1rem;
font-size: 1.2em;
}
.sidebar li[data-heading="3"] {
margin-top: 0.5rem;
font-size: 1.1em;
}
.sidebar li[data-heading]:first-child,
.sidebar li[data-heading] + li[data-heading] {
margin-top: 0;
}

49
crates/aiken-project/templates/module.html
View File

@@ -22,8 +22,14 @@
{% if !functions.is_empty() %}
<h2>Functions</h2>
<ul>
{% for function in functions %}
<li><a href="#{{ function.name }}">{{ function.name }}</a></li>
{% for function_or_section in functions %}
{% match function_or_section %}
{% when Interspersed::Function with (function) %}
<li><a href="#{{ function.name }}">{{ function.name }}</a></li>
{% when Interspersed::Section with (section) %}
<li data-heading="{{ section.heading }}"><a href="#{{ section.title|urlencode }}">{{ section.title }}</a></li>
{% endmatch %}
{% endfor %}
</ul>
{% endif %}
@@ -118,20 +124,33 @@
<h1 id="module-functions" class="module-member-kind">
<a href="#module-functions">Functions</a>
</h1>
{% for function in functions %}
<div class="member">
<div class="member-name">
<h2 id="{{ function.name }}"><pre class="hljs language-aiken">{{ function.signature }}</pre></h2>
{% if !function.source_url.is_empty() %}
<!-- TODO: support source linking
<a class="member-source" alt="View Source" title="View Source" href="{{ function.source_url|safe }}">
&lt;/&gt;
</a>
-->
{% for function_or_section in functions %}
{% match function_or_section %}
{% when Interspersed::Function with (function) %}
<div class="member">
<div class="member-name">
<h2 id="{{ function.name }}"><pre class="hljs language-aiken">{{ function.signature }}</pre></h2>
{% if !function.source_url.is_empty() %}
<!-- TODO: support source linking
<a class="member-source" alt="View Source" title="View Source" href="{{ function.source_url|safe }}">
&lt;/&gt;
</a>
-->
{% endif %}
</div>
<div class="rendered-markdown">{{ function.documentation|safe }}</div>
</div>
{% when Interspersed::Section with (section) %}
{% if section.heading == 1 %}
<h2 id="{{ section.title|urlencode }}" class="module-heading"><a href="#{{ section.title|urlencode }}">{{ section.title }}</a></h2>
{% else if section.heading == 2 %}
<h2 id="{{ section.title|urlencode }}" class="module-heading"><a href="#{{ section.title|urlencode }}">{{ section.title }}</a></h3>
{% else if section.heading == 3 %}
<h3 id="{{ section.title|urlencode }}" class="module-heading"><a href="#{{ section.title|urlencode }}">{{ section.title }}</a></h4>
{% else %}
<h4 id="{{ section.title|urlencode }}" class="module-heading"><a href="#{{ section.title|urlencode }}">{{ section.title }}</a></h5>
{% endif %}
</div>
<div class="rendered-markdown">{{ function.documentation|safe }}</div>
</div>
{% endmatch %}
{% endfor %}
</section>
{% endif %}