docs: add custom html theme
authorErik Faye-Lund <kusmabite@gmail.com>
Wed, 6 Jan 2021 13:00:52 +0000 (14:00 +0100)
committerMarge Bot <emma+marge@anholt.net>
Wed, 26 Apr 2023 22:45:41 +0000 (22:45 +0000)
This custom theme will make the docs look more like the main website,
which makes it slightly less confusing to navigate around when crossing
between the two.

The icon link.svg is from Feathericons:
https://feathericons.com/?query=link

Reviewed-by: Eric Engestrom <eric@igalia.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/8399>

docs/mesa3d_theme/layout.html [new file with mode: 0644]
docs/mesa3d_theme/search.html [new file with mode: 0644]
docs/mesa3d_theme/static/chevron-up.svg [new file with mode: 0644]
docs/mesa3d_theme/static/link.svg [new file with mode: 0644]
docs/mesa3d_theme/static/logo.svg [new file with mode: 0644]
docs/mesa3d_theme/static/menu.css [new file with mode: 0644]
docs/mesa3d_theme/static/rst.css [new file with mode: 0644]
docs/mesa3d_theme/static/screen.css_t [new file with mode: 0644]
docs/mesa3d_theme/theme.conf [new file with mode: 0644]

diff --git a/docs/mesa3d_theme/layout.html b/docs/mesa3d_theme/layout.html
new file mode 100644 (file)
index 0000000..e7312d7
--- /dev/null
@@ -0,0 +1,173 @@
+{% extends "basic/layout.html" %}
+
+{% block css %}
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-GLhlTQ8iRABdZLl6O3oVMWSktQOp6b7In1Zl3/Jr59b6EGGoI1aFkw7cmDA6j6gD" crossorigin="anonymous">
+    {{ css() }}
+{% endblock %}
+
+{% block extrahead %}
+<script>
+  (() => {
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const update = (m) => document.documentElement.setAttribute('data-bs-theme', m.matches ? 'dark' : 'light');
+    mq.addEventListener('change', (e) => update(e));
+    update(mq);
+  })();
+</script>
+{% endblock %}
+
+{% block body_tag %}
+  <body class="d-flex flex-column h-100">
+{% endblock %}
+
+{% block relbar1 %}{% endblock %}
+{% block relbar2 %}{% endblock %}
+
+{% block header %}
+  <nav class="navbar navbar-expand-lg navbar-dark bg-dark-subtle" data-bs-theme="dark">
+    <div class="container">
+      <div class="d-flex flex-row">
+        <a class="navbar-brand" href="https://www.mesa3d.org/">
+          <img class="d-inline-block align-bottom" src="{{ pathto('_static/logo.svg', 1) }}" alt="" width="30" height="30">
+          Mesa 3D
+        </a>
+      </div>
+
+      <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+      </button>
+
+      <div class="collapse navbar-collapse" id="navbarSupportedContent">
+        <ul class="navbar-nav ms-auto">
+
+          <li class="nav-item">
+            <a class="nav-link" href="https://www.mesa3d.org/" title="Home">Home</a>
+          </li>
+
+          <li class="nav-item">
+            <a class="nav-link" href="https://www.mesa3d.org/news/" title="News">News</a>
+          </li>
+
+          <li class="nav-item">
+            <a class="nav-link{% if pagename == 'download' %} active{% endif %}" href="{{ pathto('download') }}" title="">Getting Started</a>
+          </li>
+
+          <li class="nav-item">
+            <a class="nav-link active" href="{{ pathto(root_doc) }}" title="">Documentation</a>
+          </li>
+
+        </ul>
+      </div>
+    </div>
+  </nav>
+{% endblock %}
+
+{% block content %}
+  <div class="container my-3">
+    <div class="row">
+      <main class="body col-12 col-lg-9 order-1 order-lg-2" role="main">
+        {% block body %}{% endblock %}
+      </main>
+
+      {% block navigation %}
+      <nav id="menu" class="rounded col-12 col-lg-3 order-2 order-lg-1 bg-dark-subtle pb-3">
+        <div class="my-3" role="search">
+          <form id="search-form" action="{{ pathto('search') }}" method="get">
+            <div class="form-group">
+              <input class="form-control" type="text" name="q" placeholder="Search docs" />
+              <input type="hidden" name="check_keywords" value="yes" />
+              <input type="hidden" name="area" value="default" />
+            </div>
+          </form>
+        </div>
+
+        {% block menu %}
+        {% set toctree = toctree(maxdepth=4, collapse=True, includehidden=True, titles_only=False) %}
+        {% if toctree %}
+          {{ toctree }}
+        {% else %}
+          {{ toc }}
+        {% endif %}
+        {% endblock %}
+      </nav>
+      {% endblock %}
+    </div>
+  </div>
+{% endblock %}
+
+{% block footer %}
+  <footer class="footer py-3 bg-body-tertiary text-muted">
+    <div class="container">
+      <div class="row">
+
+        <div class="col-12 col-lg-3">
+          <h6 class="text-body">Documentation</h6>
+          <ul class="list-unstyled">
+            <li><a href="https://docs.mesa3d.org/license.html">License</a></li>
+            <li><a href="https://docs.mesa3d.org/faq.html">FAQ</a></li>
+            <li><a href="https://docs.mesa3d.org/download.html">Getting Started</a></li>
+          </ul>
+        </div>
+
+        <div class="col-12 col-lg-3">
+          <h6 class="text-body">Community</h6>
+          <ul class="list-unstyled">
+            <li><a href="https://gitlab.freedesktop.org/mesa">GitLab</a></li>
+            <li><a href="https://docs.mesa3d.org/lists.html">Mailing Lists</a></li>
+            <li><a href="https://docs.mesa3d.org/bugs.html">Report a Bug</a></li>
+          </ul>
+        </div>
+
+        <div class="col-12 col-lg-3">
+          <h6 class="text-body">More</h6>
+          <ul class="list-unstyled">
+            <li><a href="/website/">About Mesa3D.org</a></li>
+            <li><a href="https://docs.mesa3d.org/thanks.html">Acknowledgements</a></li>
+            <li><a href="https://dri.freedesktop.org/wiki/">Mesa / DRI Wiki</a></li>
+          </ul>
+        </div>
+
+        <div class="col-12 col-lg-3">
+          <p>Hosted by <a href="https://www.freedesktop.org/">Freedesktop.org</a></p>
+          <p><a href="https://gitlab.freedesktop.org/mesa/mesa3d.org/-/blob/main/content/_index.html">Edit this page</a></p>
+        </div>
+
+      </div>
+    </div>
+  </footer>
+  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/js/bootstrap.bundle.min.js" integrity="sha384-w76AqPfDkMBDXo30jS1Sgez6pr3x5MlQ1ZAGC+nuZB+EYdgRZgiwxhTBTkF7CXvN" crossorigin="anonymous"></script>
+  <script>
+  (() => {
+    const collapseElementList = document.querySelectorAll('#menu > .caption + ul');
+    // Add Bootstrap collapse components to the expandable menu-captions
+    [...collapseElementList].forEach(collapseEl => {
+      // disable transition if we need toggling
+      const toggle = collapseEl.classList.contains('current');
+      if (toggle)
+        collapseEl.style.transition = "none";
+      else
+        collapseEl.previousElementSibling.classList.add('collapsed');
+
+      // enable collapse
+      collapseEl.classList.add('collapse');
+      collapseEl.previousElementSibling.classList.add('collapse-icon');
+      const collapse = new bootstrap.Collapse(collapseEl, {
+        toggle: toggle
+      });
+
+      // disable transition-override again
+      if (toggle) {
+        collapseEl.addEventListener('shown.bs.collapse', event => {
+          collapseEl.style.removeProperty('transition');
+        }, {once : true})
+      }
+
+      // collapse on click on previous element
+      collapseEl.previousElementSibling.addEventListener('click', (event) => {
+        collapse.toggle();
+        collapseEl.previousElementSibling.classList.toggle('collapsed');
+      });
+    });
+  })();
+  </script>
+{% endblock %}
diff --git a/docs/mesa3d_theme/search.html b/docs/mesa3d_theme/search.html
new file mode 100644 (file)
index 0000000..f369ed6
--- /dev/null
@@ -0,0 +1,15 @@
+{% extends "basic/search.html" %}
+
+{% block scriptwarning %}
+<div id="fallback" class="alert alert-warning">
+<script>$('#fallback').hide();</script>
+<h5>{{ _('Warning') }}</h5>
+<p>
+{% trans %}Please activate JavaScript to enable the search
+functionality.{% endtrans %}
+</p>
+</div>
+{% endblock %}
+
+{% block searchbox %}
+{% endblock %}
diff --git a/docs/mesa3d_theme/static/chevron-up.svg b/docs/mesa3d_theme/static/chevron-up.svg
new file mode 100644 (file)
index 0000000..0ab171b
--- /dev/null
@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="10" height="16" viewBox="0 0 10 16">
+  <style>
+    @media (prefers-color-scheme:dark) {
+      svg {
+        fill: white;
+      }
+    }
+  </style>
+  <path d="M10 10l-1.5 1.5L5 7.75 1.5 11.5 0 10l5-5 5 5z"/>
+</svg>
diff --git a/docs/mesa3d_theme/static/link.svg b/docs/mesa3d_theme/static/link.svg
new file mode 100644 (file)
index 0000000..e9e660d
--- /dev/null
@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#000" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <style>
+    @media (prefers-color-scheme:dark) {
+      svg {
+        stroke: white;
+      }
+    }
+  </style>
+  <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
+</svg>
diff --git a/docs/mesa3d_theme/static/logo.svg b/docs/mesa3d_theme/static/logo.svg
new file mode 100644 (file)
index 0000000..1028c6d
--- /dev/null
@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.2" viewBox="-1 -1 15 15">
+  <rect x="-1" y="-1" width="15" height="15" rx="4" ry="4" />
+  <path fill="#cc1a00" d="M4.008 4.213l-.338.04L3.498 5l-.275.078-.537-.547-.311.143.068.763-.238.16-.68-.355-.252.233.301.705-.178.224-.755-.127-.166.297.504.578-.1.27-.758.113-.068.334.658.395-.012.287-.685.34.039.34.748.171.078.276-.547.537.143.31.763-.068.158.238-.353.68.23.25.707-.299.225.176-.129.758.299.166.578-.504.27.1.111.757.336.067.394-.657.286.01.341.688.34-.041.17-.746.278-.079.537.547.308-.142-.066-.764.238-.16.68.355.25-.232-.301-.705.178-.225.756.127.168-.297-.504-.578.1-.27.757-.11.066-.337-.658-.394L8 8.55l.688-.342-.042-.34-.748-.172-.076-.275.547-.537-.142-.31-.764.068-.16-.239.355-.68-.232-.25-.705.301-.225-.177.127-.756-.299-.168-.578.504-.267-.1-.114-.758-.334-.066-.394.658L4.35 4.9l-.342-.687zM4.35 7.55l.308.049.28.14.22.223.143.277.049.31-.05.31-.142.279-.22.22-.28.143-.308.049-.309-.049-.28-.143-.22-.22-.143-.28-.048-.308.048-.31.143-.278.22-.223.28-.14.309-.05z">
+  </path>
+  <path fill="#0c3" d="M10.818 6.229l-.369.671-.258.02-.466-.606-.342.143.097.758-.197.168-.734-.215-.194.314.526.559-.06.25-.721.26.029.367.752.143.1.238-.432.633.24.279.691-.326.221.135.024.765.357.086.367-.672.26-.02.467.606.342-.14-.098-.76.197-.168.735.215.191-.315-.523-.556.06-.252.72-.258-.029-.37-.751-.14-.1-.24.432-.633-.24-.28-.692.327-.22-.135-.024-.766-.358-.085zm-.447 1.828l.307.048.217.217.048.307-.14.275-.276.139-.304-.047-.22-.219-.046-.304.139-.276.275-.14z">
+  </path>
+  <path fill="#33f" d="M4.168.002l-.367.041-.115.756-.237.107-.646-.408-.272.25.352.68-.13.224-.763.051-.072.361.684.344.029.256-.59.49.154.336.754-.125.176.192-.19.742.323.181.537-.544.254.052.283.711.367-.043.115-.756.237-.107.646.408.272-.248-.352-.68.13-.226.763-.049.072-.361-.684-.344-.029-.258.59-.488-.154-.336-.754.123-.176-.191.19-.74L5.241.22l-.537.543L4.45.712 4.167.001zm.24 1.059l.729.337.388.704-.097.796-.547.588-.79.155-.728-.34-.388-.703.097-.797.547-.588.79-.152z">
+  </path>
+</svg>
diff --git a/docs/mesa3d_theme/static/menu.css b/docs/mesa3d_theme/static/menu.css
new file mode 100644 (file)
index 0000000..cacf8da
--- /dev/null
@@ -0,0 +1,76 @@
+#menu {
+  height: max-content;
+}
+
+#menu .caption {
+  cursor: pointer;
+  margin-bottom: 0;
+}
+
+#menu a {
+  color: inherit;
+  text-overflow: ellipsis;
+  overflow: hidden;
+  display: block;
+  text-decoration: none;
+}
+
+#menu a[href^="#"] {
+  color: var(--bs-secondary-color);
+}
+
+#menu .caption,
+#menu li {
+  margin-top: 0.25rem;
+}
+
+#menu .caption-text,
+#menu li.current {
+  font-weight: bold;
+}
+
+#menu li.current > a {
+  color: var(--bs-body-color)
+}
+
+#menu li.current li {
+  font-weight: initial;
+}
+
+#menu ul {
+  list-style-type: none;
+  padding-left: 0;
+  padding-left: 1rem;
+  margin-bottom: 0.5rem;
+}
+
+#menu ul:last-of-type {
+  margin-bottom: 0;
+}
+
+#menu p.caption::after {
+  display: block;
+  content: '';
+  clear: both;
+}
+
+#menu .collapse-icon .caption-text:after {
+  content: ' ';
+  float: right;
+  display: block;
+  background-image: url('chevron-up.svg');
+  background-size: 1.5em 1.5em;
+  opacity: 0.25;
+  width: 1.5em;
+  height: 1.5em;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  #menu .collapse-icon .caption-text:after {
+    transition: transform 0.2s;
+  }
+}
+
+#menu .collapse-icon.collapsed .caption-text:after {
+  transform: rotate(180deg);
+}
diff --git a/docs/mesa3d_theme/static/rst.css b/docs/mesa3d_theme/static/rst.css
new file mode 100644 (file)
index 0000000..421a982
--- /dev/null
@@ -0,0 +1,73 @@
+.headerlink {
+  color: transparent;
+  display: inline-block;
+  vertical-align: middle;
+  background-image: url('link.svg');
+  background-size: 1ex 1ex;
+  margin-left: 0.25rem;
+  opacity: 0.25;
+  width: 1ex;
+  height: 1ex;
+  user-select: none;
+}
+
+.headerlink:hover {
+  opacity: 0.5;
+}
+
+.highlight {
+  border-radius: var(--bs-border-radius-sm);
+  padding: .5rem;
+  color: var(--bs-dark);
+  margin-bottom: 1rem;
+}
+
+.highlight > pre {
+  margin-bottom: 0;
+}
+
+dd {
+  margin-left: 2rem;
+}
+
+.sig {
+  font-family: var(--bs-font-monospace);
+  color: var(--bs-code-color);
+}
+
+dt.sig {
+  color: var(--bs-heading-color, inherit);
+}
+
+dl > .sig.c {
+  background-color: var(--bs-secondary-bg);
+  color: var(--bs-secondary);
+  padding: 0.25rem 0.5rem;
+  border-radius: var(--bs-border-radius-sm);
+}
+
+dl > .sig.c .sig-name {
+  color: var(--bs-secondary-text);
+}
+
+main .container {
+  padding: 0;
+}
+
+li > p:last-of-type,
+th > p:last-of-type,
+td > p:last-of-type,
+.alert > p:last-of-type {
+  margin-bottom: 0;
+}
+
+div.code-block-caption {
+  font-size: .875em;
+  color: var(--bs-secondary-color);
+  margin-bottom: 0.5rem;
+}
+
+.alert a {
+  font-weight: 700;
+  color: var(--bs-alert-link-color);
+}
diff --git a/docs/mesa3d_theme/static/screen.css_t b/docs/mesa3d_theme/static/screen.css_t
new file mode 100644 (file)
index 0000000..7da46e2
--- /dev/null
@@ -0,0 +1,98 @@
+@import url("menu.css");
+@import url("rst.css");
+
+html {
+  height: 100%;
+}
+
+.navbar {
+  flex: none;
+}
+
+
+h1, h2, h3, h4, h5, h6,
+.h1, .h2, .h3, .h4, .h5, .h6 {
+  font-weight: 600 !important;
+}
+
+footer {
+  flex: 1;
+}
+
+footer a:any-link {
+  color: inherit;
+  text-decoration: none;
+}
+
+{%- if docutils_version_info[:2] < (0, 18) %}
+
+a.brackets::before,
+span.brackets::before {
+  content: "[";
+}
+
+a.brackets::after,
+span.brackets::after {
+  content: "]";
+}
+
+span.brackets {
+  font-weight: normal;
+}
+
+dl.footnote,
+dl.citation {
+  margin-bottom: 0;
+}
+
+dl.footnote > dt,
+dl.citation > dt {
+  float: left;
+}
+dl.footnote > dd,
+dl.citation > dd {
+  margin-bottom: 0;
+}
+dl.footnote > dd:after,
+dl.citation > dd:after {
+  content: "";
+  clear: both;
+}
+dl.footnote > dd > p {
+  margin-left: 2rem;
+}
+dl.citation > dd > p {
+  margin-left: 4rem;
+}
+dl.footnote > dd > p:last-of-type,
+dl.citation > dd > p:last-of-type {
+  margin-bottom: 0;
+}
+
+{%- else %}
+
+aside.footnote > span,
+div.citation > span {
+  float: left;
+}
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+  padding-right: 0.5rem;
+}
+aside.footnote > p {
+  margin-left: 2rem;
+}
+div.citation > p {
+  margin-left: 4rem;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
+    margin-bottom: 0;
+}
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
+    content: "";
+    clear: both;
+}
+
+{%- endif %}
diff --git a/docs/mesa3d_theme/theme.conf b/docs/mesa3d_theme/theme.conf
new file mode 100644 (file)
index 0000000..6478dad
--- /dev/null
@@ -0,0 +1,5 @@
+[theme]
+inherit = basic
+stylesheet = screen.css
+pygments_style = default
+pygments_dark_style = github-dark