Skip to content

Commit 4dadb97

Browse files
cpucpu
committed
add an API docs website powered by Zola
This commit adds a Zola[0] website that can template the API docs JSON data into a nice website showing off our API. The choice of Zola (and the initial CSS/config) are inspired by the https://rustls.dev website which also uses Zola. To use: ``` cargo run --bin docgen > website/static/api.json cd website && zola serve open http://locahost:1111 ``` [0]: https://www.getzola.org/
1 parent 59f57c4 commit 4dadb97

File tree

11 files changed

+324
-0
lines changed

11 files changed

+324
-0
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@ librustls/cmake-build*
66
.vs
77
debian/usr
88
debian/DEBIAN
9+
/website/static/api.json
10+
/website/public

‎website/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Source for the website at `https://ffi.rustls.dev/`
2+
3+
This uses [Zola](https://www.getzola.org/).
4+
5+
Run `zola serve` in this directory to run a local copy.

‎website/config.toml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# The URL the site will be built for
2+
base_url = "https://ffi.rustls.dev/"
3+
4+
# Whether to automatically compile all Sass files in the sass directory
5+
compile_sass = false
6+
7+
# Whether to build a search index to be used later on by a JavaScript library
8+
build_search_index = false
9+
10+
[markdown]
11+
# Whether to do syntax highlighting
12+
# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
13+
highlight_code = true
14+
15+
[slugify]
16+
paths_keep_dates = true
17+
18+
[extra]

‎website/content/_index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
+++
2+
title = "rustls-ffi API docs"
3+
template = "index.html"
4+
+++

‎website/static/GeneralSans-Variable.woff2

37.2 KB
Binary file not shown.

‎website/static/rustls-ferris.png

487 KB
Loading

‎website/static/style.css

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
/* Base styles */
2+
body {
3+
background-image: linear-gradient(to right top, #2f4858, #2e4e6c, #3a517f, #54528e, #744e95);
4+
font-family: sans-serif;
5+
margin: 0;
6+
}
7+
8+
/* logo image */
9+
img#baby-logo {
10+
filter: drop-shadow(0px 0.1em 0.2em rgba(0, 0, 0, 0.2));
11+
max-height: 10%;
12+
max-width: 20%;
13+
display: block;
14+
margin-left: 1em;
15+
margin-top: 1em;
16+
}
17+
18+
/* Text colors */
19+
* { color: white; }
20+
21+
h1, h2, h3 { color: #c5d8ff; }
22+
23+
.toc a { color: #c5d8ff; }
24+
25+
/* Layout */
26+
.container {
27+
box-sizing: border-box;
28+
margin: 0 auto;
29+
max-width: 1200px;
30+
padding: 0 1rem;
31+
width: 95%;
32+
}
33+
34+
/* Typography and Links */
35+
h2 .header-link,
36+
h3 .header-link {
37+
color: inherit;
38+
display: block;
39+
text-decoration: none;
40+
}
41+
42+
.back-to-top a {
43+
background: rgba(255, 255, 255, 0.1);
44+
border-radius: 1em;
45+
color: rgba(255, 255, 255, 0.7);
46+
font-size: 0.85rem;
47+
padding: 0.4em 0.8em;
48+
text-decoration: none;
49+
transition: all 0.2s ease;
50+
}
51+
52+
.back-to-top a:hover {
53+
background: rgba(255, 255, 255, 0.15);
54+
color: rgba(255, 255, 255, 0.9);
55+
}
56+
57+
/* Code and Pre blocks */
58+
p > code {
59+
background: rgba(0, 0, 0, 0.1);
60+
border-radius: 1em;
61+
padding: 0.2em;
62+
}
63+
64+
pre {
65+
background: rgba(0, 0, 0, 0.1);
66+
border-radius: 1em;
67+
max-width: 100%;
68+
padding: 1em;
69+
white-space: pre-wrap;
70+
margin: 1em;
71+
}
72+
73+
.variant pre {
74+
margin: 0.5em;
75+
background-color: #2b303b;
76+
color: #b48ead;
77+
}
78+
79+
code {
80+
word-break: break-all;
81+
word-wrap: break-word;
82+
}
83+
84+
/* Components */
85+
.toc {
86+
background-image: linear-gradient(to right top, #2f4858, #2e4e6c, #3a517f, #54528e, #744e95);
87+
border-radius: 1rem;
88+
box-sizing: border-box;
89+
filter: drop-shadow(0px 0px 1em rgba(0, 0, 0, 0.25));
90+
margin: 1.5rem 0;
91+
max-width: 1200px;
92+
overflow-x: auto;
93+
padding: 1.5rem;
94+
}
95+
96+
.item {
97+
background: rgba(255, 255, 255, 0.07);
98+
backdrop-filter: blur(2px);
99+
border: 1px solid rgba(255, 255, 255, 0.1);
100+
border-radius: 1rem;
101+
margin: 1.5rem 0;
102+
padding: 1.5rem;
103+
transition: background 0.2s ease;
104+
}
105+
106+
section {
107+
background-image: linear-gradient(to right top, #2f4858, #2e4e6c, #3a517f, #54528e, #744e95);
108+
border-radius: 1rem;
109+
filter: drop-shadow(0px 0px 1em rgba(0, 0, 0, 0.25));
110+
margin: 2em 0;
111+
max-width: 100%;
112+
padding: 2em;
113+
}
114+
115+
/* Anchors */
116+
h2, h3, .variant {
117+
position: relative;
118+
}
119+
120+
.variant a {
121+
text-decoration: none;
122+
}
123+
124+
h2 .anchor,
125+
h3 .anchor,
126+
.variant .anchor {
127+
color: #ac66e6;
128+
left: -1em;
129+
opacity: 0;
130+
position: absolute;
131+
text-decoration: none;
132+
transition: opacity 0.2s ease-in-out;
133+
}
134+
135+
h2:hover .anchor,
136+
h3:hover .anchor,
137+
.variant:hover .anchor {
138+
opacity: 1;
139+
}
140+
141+
/* Media Queries */
142+
@media (max-width: 768px) {
143+
.container {
144+
padding: 0 0.5rem;
145+
width: 100%;
146+
}
147+
.variant {
148+
margin-left: 1rem;
149+
}
150+
}
151+
152+
.feature-box {
153+
display: flex;
154+
align-items: center;
155+
gap: 0.75rem;
156+
padding: 0.75rem 1rem;
157+
margin: 1rem 0;
158+
background: #744e95;
159+
border-left: 5px solid #3b82f6;
160+
border-right: 1px solid #3b82f6;
161+
border-top: 1px solid #3b82f6;
162+
border-bottom: 1px solid #3b82f6;
163+
border-radius: 0.5em;
164+
}
165+
166+
a:has(code) {
167+
text-decoration: none;
168+
}
169+
a:has(code):hover {
170+
text-decoration: #ac66e6 overline underline;
171+
text-decoration-thickness: 2px;
172+
}
173+
174+
a code {
175+
color: #c5d8ff;
176+
}

‎website/templates/_api_section.html

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{% macro render_section(section_id, title, items) %}
2+
<section id="{{ section_id }}" class="section">
3+
{{ macros::section_header(id=section_id, title=title) }}
4+
{{ macros::toc_list(items=items) }}
5+
6+
{% for item in items %}
7+
<div id="{{ item.anchor }}" class="item">
8+
{{ macros::item_header(anchor=item.anchor, name=item.name) }}
9+
10+
{% if item.feature %}
11+
<div class="feature-box">
12+
<svg class="feature-icon" viewBox="0 0 20 20" width="16" height="16">
13+
<circle cx="10" cy="10" r="9" fill="none" stroke="currentColor" stroke-width="1.5"/>
14+
<circle cx="10" cy="6" r="1" fill="currentColor"/>
15+
<path d="M10 9v7" stroke="currentColor" stroke-width="1.5"/>
16+
</svg>
17+
<span>Requires feature: <strong>{{ item.feature }}</strong></span>
18+
</div>
19+
{% endif %}
20+
21+
{{ item.comment | markdown | safe }}
22+
23+
{% if section_id == "enums" %}
24+
{% for variant in item.variants %}
25+
<div id="{{ variant.anchor }}" class="variant">
26+
{% if variant.comment %}
27+
{{ variant.comment | markdown | safe }}
28+
{% endif %}
29+
<a href="#{{ variant.anchor }}" class="anchor">#</a>
30+
<a href="#{{ variant.anchor }}" class="header-link">
31+
<pre class="variant">{{ variant.name }} = {{ variant.value }}</pre>
32+
</a>
33+
</div>
34+
{% endfor %}
35+
{% else %}
36+
{{ item.text | markdown | safe }}
37+
{% endif %}
38+
39+
{{ macros::back_to_top() }}
40+
</div>
41+
{% endfor %}
42+
</section>
43+
{% endmacro render_section %}

‎website/templates/base.html

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<html>
2+
<head>
3+
<title>rustls: {{ page.title | default (value="C FFI bindings for Rustls") }}</title>
4+
<meta name="viewport" content="width=device-width, initial-scale=1">
5+
<meta charset="UTF-8">
6+
<link rel="stylesheet" href="{{ get_url(path="style.css") }}">
7+
</head>
8+
<body>
9+
<a href="{{ config.base_url }}">
10+
<img id="baby-logo" src="{{ get_url(path="rustls-ferris.png") }}">
11+
</a>
12+
{% block lede %} {% endblock %}
13+
{% block content %} {% endblock %}
14+
</body>
15+
</html>

‎website/templates/index.html

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{% extends "base.html" %}
2+
{% import "macros.html" as macros %}
3+
{% import "_api_section.html" as api_section %}
4+
5+
{% block content %}
6+
{% set data = load_data(path="static/api.json") %}
7+
{% set section_ids = ["structs", "functions", "callbacks", "enums", "externs", "aliases"] %}
8+
{% set section_titles = ["Structs", "Functions", "Callbacks", "Enums", "Externs", "Type Aliases"] %}
9+
10+
<div class="container">
11+
<h1>rustls-ffi API Documentation</h1>
12+
13+
<div class="toc">
14+
<h2>Table of Contents</h2>
15+
<ul>
16+
{% for id in section_ids %}
17+
{% if data[id] %}
18+
<li><a href="#{{ id }}">{{ section_titles[loop.index0] }}</a></li>
19+
{% endif %}
20+
{% endfor %}
21+
</ul>
22+
</div>
23+
24+
{% for id in section_ids %}
25+
{% if data[id] %}
26+
{{ api_section::render_section(
27+
section_id=id,
28+
title=section_titles[loop.index0],
29+
items=data[id])
30+
}}
31+
{% endif %}
32+
{% endfor %}
33+
</div>
34+
{% endblock %}

‎website/templates/macros.html

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{% macro section_header(id, title) %}
2+
<h2>
3+
<a href="#{{ id }}" class="anchor">#</a>
4+
<a href="#{{ id }}" class="header-link">{{ title }}</a>
5+
</h2>
6+
{% endmacro section_header %}
7+
8+
{% macro item_header(anchor, name) %}
9+
<h3>
10+
<a href="#{{ anchor }}" class="anchor">#</a>
11+
<a href="#{{ anchor }}" class="header-link">{{ name }}</a>
12+
</h3>
13+
{% endmacro item_header %}
14+
15+
{% macro toc_list(items) %}
16+
<div class="toc">
17+
<ul>
18+
{% for item in items %}
19+
<li><a href="#{{ item.anchor }}">{{ item.name }}</a></li>
20+
{% endfor %}
21+
</ul>
22+
</div>
23+
{% endmacro toc_list %}
24+
25+
{% macro back_to_top() %}
26+
<p class="back-to-top"><a href="#top">Back to top ↑</a></p>
27+
{% endmacro back_to_top %}

0 commit comments

Comments
 (0)