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/

.gitignore

@@ -4,3 +4,5 @@ librustls/cmake-build*
 .idea
 .venv
 .vs
+/website/static/api.json
+/website/public

website/README.md

@@ -0,0 +1,5 @@
+Source for the website at `https://ffi.rustls.dev/`
+
+This uses [Zola](https://www.getzola.org/).
+
+Run `zola serve` in this directory to run a local copy.

website/config.toml

@@ -0,0 +1,19 @@
+# The URL the site will be built for
+# TODO(@cpu): set up https://ffi.rustls.dev DNS
+base_url = "https://rustls.github.io/rustls-ffi/"
+
+# Whether to automatically compile all Sass files in the sass directory
+compile_sass = false
+
+# Whether to build a search index to be used later on by a JavaScript library
+build_search_index = false
+
+[markdown]
+# Whether to do syntax highlighting
+# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
+highlight_code = true
+
+[slugify]
+paths_keep_dates = true
+
+[extra]

website/content/_index.md

@@ -0,0 +1,4 @@
++++
+title = "rustls-ffi API docs"
+template = "index.html"
++++

website/static/style.css

@@ -0,0 +1,150 @@
+/* Base styles */
+body {
+  background-image: linear-gradient(to right top, #2f4858, #2e4e6c, #3a517f, #54528e, #744e95);
+  font-family: sans-serif;
+  margin: 0;
+}
+
+/* logo image */
+img#baby-logo {
+  filter: drop-shadow(0px 0.1em 0.2em rgba(0, 0, 0, 0.2));
+  max-height: 10%;
+  max-width: 20%;
+  display: block;
+  margin-left: 1em;
+  margin-top: 1em;
+}
+
+/* Text colors */
+* { color: white; }
+
+h1, h2, h3 { color: #c5d8ff; }
+
+.toc a { color: #c5d8ff; }
+
+/* Layout */
+.container {
+  box-sizing: border-box;
+  margin: 0 auto;
+  max-width: 1200px;
+  padding: 0 1rem;
+  width: 95%;
+}
+
+/* Typography and Links */
+h2 .header-link,
+h3 .header-link {
+  color: inherit;
+  display: block;
+  text-decoration: none;
+}
+
+.back-to-top a {
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 1em;
+  color: rgba(255, 255, 255, 0.7);
+  font-size: 0.85rem;
+  padding: 0.4em 0.8em;
+  text-decoration: none;
+  transition: all 0.2s ease;
+}
+
+.back-to-top a:hover {
+  background: rgba(255, 255, 255, 0.15);
+  color: rgba(255, 255, 255, 0.9);
+}
+
+/* Code and Pre blocks */
+p > code {
+  background: rgba(0, 0, 0, 0.1);
+  border-radius: 1em;
+  padding: 0.2em;
+}
+
+pre {
+  background: rgba(0, 0, 0, 0.1);
+  border-radius: 1em;
+  max-width: 100%;
+  padding: 1em;
+  white-space: pre-wrap;
+  margin: 1em;
+}
+
+.variant pre {
+  margin: 0.5em;
+  background-color: #2b303b;
+  color: #b48ead;
+}
+
+code {
+  word-break: break-all;
+  word-wrap: break-word;
+}
+
+/* Components */
+.toc {
+  background-image: linear-gradient(to right top, #2f4858, #2e4e6c, #3a517f, #54528e, #744e95);
+  border-radius: 1rem;
+  box-sizing: border-box;
+  filter: drop-shadow(0px 0px 1em rgba(0, 0, 0, 0.25));
+  margin: 1.5rem 0;
+  max-width: 1200px;
+  overflow-x: auto;
+  padding: 1.5rem;
+}
+
+.item {
+  background: rgba(255, 255, 255, 0.07);
+  backdrop-filter: blur(2px);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 1rem;
+  margin: 1.5rem 0;
+  padding: 1.5rem;
+  transition: background 0.2s ease;
+}
+
+section {
+  background-image: linear-gradient(to right top, #2f4858, #2e4e6c, #3a517f, #54528e, #744e95);
+  border-radius: 1rem;
+  filter: drop-shadow(0px 0px 1em rgba(0, 0, 0, 0.25));
+  margin: 2em 0;
+  max-width: 100%;
+  padding: 2em;
+}
+
+/* Anchors */
+h2, h3, .variant {
+  position: relative;
+}
+
+.variant a {
+  text-decoration: none;
+}
+
+h2 .anchor,
+h3 .anchor,
+.variant .anchor {
+  color: #ac66e6;
+  left: -1em;
+  opacity: 0;
+  position: absolute;
+  text-decoration: none;
+  transition: opacity 0.2s ease-in-out;
+}
+
+h2:hover .anchor,
+h3:hover .anchor,
+.variant:hover .anchor {
+  opacity: 1;
+}
+
+/* Media Queries */
+@media (max-width: 768px) {
+  .container {
+    padding: 0 0.5rem;
+    width: 100%;
+  }
+  .variant {
+    margin-left: 1rem;
+  }
+}

website/templates/_api_section.html

@@ -0,0 +1,32 @@
+{% macro render_section(section_id, title, items) %}
+<section id="{{ section_id }}" class="section">
+    {{ macros::section_header(id=section_id, title=title) }}
+    {{ macros::toc_list(items=items) }}
+
+    {% for item in items %}
+    <div id="{{ item.anchor }}" class="item">
+        {{ macros::item_header(anchor=item.anchor, name=item.name) }}
+
+        {{ item.comment | markdown | safe }}
+
+        {% if section_id == "enums" %}
+        {% for variant in item.variants %}
+        <div id="{{ variant.anchor }}" class="variant">
+            {% if variant.comment %}
+            {{ variant.comment | markdown | safe }}
+            {% endif %}
+            <a href="#{{ variant.anchor }}" class="anchor">#</a>
+            <a href="#{{ variant.anchor }}" class="header-link">
+                <pre class="variant">{{ variant.name }} = {{ variant.value }}</pre>
+            </a>
+        </div>
+        {% endfor %}
+        {% else %}
+        {{ item.text | markdown | safe }}
+        {% endif %}
+
+        {{ macros::back_to_top() }}
+    </div>
+    {% endfor %}
+</section>
+{% endmacro render_section %}

website/templates/base.html

@@ -0,0 +1,15 @@
+<html>
+  <head>
+    <title>rustls: {{ page.title | default (value="C FFI bindings for Rustls") }}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta charset="UTF-8">
+    <link rel="stylesheet" href="{{ get_url(path="style.css") }}">
+  </head>
+  <body>
+    <a href="{{ config.base_url }}">
+      <img id="baby-logo" src="{{ get_url(path="rustls-ferris.png") }}">
+    </a>
+    {% block lede %} {% endblock %}
+    {% block content %} {% endblock %}
+  </body>
+</html>

website/templates/index.html

@@ -0,0 +1,34 @@
+{% extends "base.html" %}
+{% import "macros.html" as macros %}
+{% import "_api_section.html" as api_section %}
+
+{% block content %}
+{% set data = load_data(path="static/api.json") %}
+{% set section_ids = ["structs", "functions", "callbacks", "enums", "externs", "aliases"] %}
+{% set section_titles = ["Structs", "Functions", "Callbacks", "Enums", "Externs", "Type Aliases"] %}
+
+<div class="container">
+    <h1>rustls-ffi API Documentation</h1>
+
+    <div class="toc">
+        <h2>Table of Contents</h2>
+        <ul>
+            {% for id in section_ids %}
+                {% if data[id] %}
+                <li><a href="#{{ id }}">{{ section_titles[loop.index0] }}</a></li>
+                {% endif %}
+            {% endfor %}
+        </ul>
+    </div>
+
+    {% for id in section_ids %}
+        {% if data[id] %}
+        {{ api_section::render_section(
+            section_id=id,
+            title=section_titles[loop.index0],
+            items=data[id])
+        }}
+        {% endif %}
+    {% endfor %}
+</div>
+{% endblock %}

website/templates/macros.html

@@ -0,0 +1,27 @@
+{% macro section_header(id, title) %}
+<h2>
+    <a href="#{{ id }}" class="anchor">#</a>
+    <a href="#{{ id }}" class="header-link">{{ title }}</a>
+</h2>
+{% endmacro section_header %}
+
+{% macro item_header(anchor, name) %}
+<h3>
+    <a href="#{{ anchor }}" class="anchor">#</a>
+    <a href="#{{ anchor }}" class="header-link">{{ name }}</a>
+</h3>
+{% endmacro item_header %}
+
+{% macro toc_list(items) %}
+<div class="toc">
+    <ul>
+        {% for item in items %}
+        <li><a href="#{{ item.anchor }}">{{ item.name }}</a></li>
+        {% endfor %}
+    </ul>
+</div>
+{% endmacro toc_list %}
+
+{% macro back_to_top() %}
+<p class="back-to-top"><a href="#top">Back to top ↑</a></p>
+{% endmacro back_to_top %}