Skip to content

Commit 419f32f

Browse files
ananosananos
committed
docs: Polish theme and structure
Signed-off-by: Anastassios Nanos <ananos@nubificus.co.uk>
1 parent 3fa60a4 commit 419f32f

File tree

11 files changed

+489
-41
lines changed

11 files changed

+489
-41
lines changed

‎.github/linters/licenserc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ header:
3838
- 'VERSION'
3939
- 'build*'
4040
- 'docs/CNAME'
41+
- 'docs/**'
42+
- 'orchestrators/**'
4143

4244
language:
4345
Go:

‎.github/workflows/publish_docs.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Deploy documentation website
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'docs/**'
8+
- 'mkdocs.yml'
9+
- 'requirements.txt'
10+
11+
permissions:
12+
contents: write # Needed for GitHub Pages deployment
13+
14+
jobs:
15+
deploy:
16+
runs-on: [base-dind-2204-amd64]
17+
18+
steps:
19+
- name: Checkout repository
20+
uses: actions/checkout@v4
21+
22+
- name: Install dependencies
23+
run: |
24+
pip3 install -r requirements.txt
25+
echo "PATH=$PATH:$HOME/.local/bin" >> "$GITHUB_ENV"
26+
27+
- name: Build and deploy MkDocs site
28+
run: |
29+
mkdocs gh-deploy --force
30+

‎docs/.nav.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
nav:
2+
- Home: index.md
3+
- Quickstart: quickstart.md
4+
- Installation: installation.md
5+
- Design:
6+
- design/*.md
7+
- Developer Guide:
8+
- developer-guide/*.md
9+
- Tutorials:
10+
- tutorials/*.md
11+
12+

docs/img/mlsysops-logo.png renamed to docs/assets/img/mlsysops-logo.png

File renamed without changes.

‎docs/assets/javascripts/console-copy.js‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
/* global document$:readonly */
2+
document$.subscribe(() => {
3+
document.querySelectorAll("pre > code").forEach((code) => {
4+
const wrapper = code.closest("div.language-console");
5+
6+
if (!wrapper) return;
7+
8+
const button = wrapper.querySelector("button.md-clipboard");
9+
if (!button) return;
10+
11+
button.addEventListener(
12+
"mouseenter",
13+
() => {
14+
// Only set data-copy once
15+
if (code.hasAttribute("data-copy")) return;
16+
17+
const text = code.textContent.trimEnd();
18+
19+
// Merge continuation lines that end with '\', and remove '$'
20+
// from prompts
21+
let lines = [];
22+
let mergeNext = false;
23+
24+
text.split("\n").forEach((line) => {
25+
// If we need to merge the current line with the next one
26+
if (mergeNext) {
27+
// Merge the line with the previous one and reset the
28+
// flag
29+
lines[lines.length - 1] += " " + line.trimStart();
30+
if (lines[lines.length - 1].endsWith(" \\")) {
31+
lines[lines.length - 1] = lines[
32+
lines.length - 1
33+
].slice(0, -2);
34+
} else if (lines[lines.length - 1].endsWith("\\")) {
35+
lines[lines.length - 1] = lines[
36+
lines.length - 1
37+
].slice(0, -1);
38+
} else {
39+
mergeNext = false;
40+
}
41+
}
42+
43+
// If the line starts with '$' and ends with '\'
44+
// (continuation line)
45+
if (line.startsWith("$ ")) {
46+
if (line.endsWith(" \\")) {
47+
// Remove "$ " and the trailing "\"
48+
lines.push(line.slice(2, -2));
49+
// Mark that we need to merge with the next line
50+
mergeNext = true;
51+
} else if (line.endsWith("\\")) {
52+
// Remove "$ " and the trailing " \"
53+
lines.push(line.slice(2, -1));
54+
mergeNext = true;
55+
} else {
56+
// If it's a prompt line without continuation, just
57+
// remove the '$'
58+
lines.push(line.slice(2));
59+
}
60+
}
61+
});
62+
63+
const cleaned = lines.join("\n");
64+
65+
code.setAttribute("data-copy", cleaned);
66+
},
67+
{ once: true },
68+
);
69+
});
70+
});

‎docs/assets/stylesheets/theme.css‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
/*
2+
* urunc Custom Theme Styling for MkDocs Material
3+
*/
4+
5+
/* =======================
6+
Light Theme: urunc
7+
======================= */
8+
[data-md-color-scheme="urunc"] {
9+
--md-primary-fg-color: #FAFAFF;
10+
--md-primary-fg-color--light: #001524;
11+
--md-primary-fg-color--dark: #001524;
12+
--md-primary-bg-color: #001524;
13+
--md-primary-bg-color--light: #001524;
14+
--md-primary-bg-color--dark: #001524;
15+
16+
--md-accent-fg-color: #FF7D00;
17+
--md-accent-fg-color--transparent: hsla(32, 100%, 55%, 0.1);
18+
19+
--md-footer-logo-dark-mode: none;
20+
--md-footer-logo-light-mode: block;
21+
}
22+
23+
/* =======================
24+
Dark Theme: Slate
25+
======================= */
26+
[data-md-color-scheme="slate"] {
27+
--md-primary-fg-color: #001524;
28+
--md-primary-fg-color--light: #841a6b;
29+
--md-primary-fg-color--dark: #001524;
30+
--md-primary-bg-color: #fff3f0;
31+
32+
--md-accent-fg-color: #FF7D00;
33+
--md-accent-fg-color--transparent: hsla(32, 100%, 55%, 0.1);
34+
35+
--md-footer-logo-dark-mode: block;
36+
--md-footer-logo-light-mode: none;
37+
}
38+
39+
/* =======================
40+
Logo Sizing
41+
======================= */
42+
.md-nav__title .md-nav__button.md-logo img {
43+
height: 2rem;
44+
}
45+
46+
#logo_light_mode {
47+
display: var(--md-footer-logo-light-mode);
48+
}
49+
50+
#logo_dark_mode {
51+
display: var(--md-footer-logo-dark-mode);
52+
}
53+
54+
/* =======================
55+
Breadcrumb Styling
56+
======================= */
57+
:root {
58+
--md-path-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8.59 16.58 13.17 12 8.59 7.41 10 6l6 6-6 6z"/></svg>');
59+
}
60+
61+
.md-path {
62+
font-size: 0.75rem;
63+
margin: 0 0.8rem;
64+
overflow: auto;
65+
padding-top: 1.2rem;
66+
}
67+
68+
.md-path:not([hidden]) {
69+
display: block;
70+
}
71+
72+
@media screen and (min-width: 76.25em) {
73+
.md-path {
74+
margin: 0 1.2rem;
75+
}
76+
}
77+
78+
.md-path__list {
79+
display: flex;
80+
align-items: center;
81+
gap: 0.25rem;
82+
list-style: none;
83+
margin: 0;
84+
padding: 0;
85+
}
86+
87+
.md-path__item:not(:first-child) {
88+
display: inline-flex;
89+
gap: 0.25rem;
90+
white-space: nowrap;
91+
}
92+
93+
.md-path__item:not(:first-child)::before {
94+
content: "";
95+
width: 0.8rem;
96+
height: 0.8rem;
97+
display: inline;
98+
background-color: var(--md-default-fg-color--lighter);
99+
mask-image: var(--md-path-icon);
100+
-webkit-mask-image: var(--md-path-icon);
101+
}
102+
103+
.md-path__link {
104+
display: flex;
105+
align-items: center;
106+
color: var(--md-default-fg-color--light);
107+
}
108+
109+
.md-path__link:hover,
110+
.md-path__link:focus {
111+
color: var(--md-accent-fg-color);
112+
}
113+
114+
/* =======================
115+
Permalink Anchor Styling
116+
======================= */
117+
.md-typeset .headerlink {
118+
font-size: 1rem;
119+
display: inline-block;
120+
vertical-align: middle;
121+
}
122+
123+
/* =======================
124+
Code Block Styling
125+
======================= */
126+
.language-console span.gp {
127+
user-select: none;
128+
-webkit-user-select: none;
129+
pointer-events: none;
130+
}
131+
132+
/* =======================
133+
General Typography (Optional)
134+
======================= */
135+
.md-typeset h1 {
136+
font-size: 2rem;
137+
border-bottom: 2px solid var(--md-accent-fg-color--transparent);
138+
padding-bottom: 0.25em;
139+
}
140+
141+
.md-typeset h2 {
142+
font-size: 1.5rem;
143+
margin-top: 2em;
144+
}
145+
146+
.md-typeset code,
147+
.md-typeset pre {
148+
font-family: 'JetBrains Mono', 'Fira Code', monospace;
149+
}
150+
151+
/* Fix active link color in dark mode sidebar */
152+
[data-md-color-scheme="slate"] .md-nav__link--active {
153+
color: var(--md-primary-bg-color) !important;
154+
font-weight: bold;
155+
}
156+
157+
[data-md-color-scheme="slate"] .md-nav__link:hover,
158+
[data-md-color-scheme="slate"] .md-nav__link:focus {
159+
color: var(--md-primary-bg-color);
160+
}
161+
162+
/* Improve contrast for all links in dark mode */
163+
[data-md-color-scheme="slate"] a {
164+
color: var(--md-primary-bg-color);
165+
}
166+
167+
/* Optional: Slight hover effect for links */
168+
[data-md-color-scheme="slate"] a:hover {
169+
text-decoration: underline;
170+
}
171+
172+
[data-md-color-scheme="urunc"] img[src$="#only-dark"],
173+
[data-md-color-scheme="urunc"] img[src$="#gh-dark-mode-only"] {
174+
display: none; /* Hide dark images in light mode */
175+
}
176+
177+
[data-md-color-scheme="slate"] img[src$="#only-light"],
178+
[data-md-color-scheme="slate"] img[src$="#gh-light-mode-only"] {
179+
display: none; /* Hide light images in dark mode */
180+
}
181+

‎docs/hooks/copyright.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# SPDX-License-Identifier: Apache-2.0
2+
3+
from datetime import datetime
4+
5+
6+
def on_config(config, **kwargs):
7+
author = config.get("site_author", "Author")
8+
year = datetime.now().year
9+
start_year = config.get("copyright", year)
10+
if start_year != year:
11+
config["copyright"] = f"Copyright &copy; {start_year} - {year} {author}"
12+
else:
13+
config["copyright"] = f"Copyright &copy; {year} {author}"
14+
return config

‎docs/overrides/main.html‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{% extends "base.html" %}
2+
3+
{% if page.ancestors %}
4+
<nav class="breadcrumbs">
5+
{% for ancestor in page.ancestors %}
6+
<a href="{{ ancestor.url }}">{{ ancestor.title }}</a> /
7+
{% endfor %}
8+
{{ page.title }}
9+
</nav>
10+
{% endif %}
11+
12+
{% block outdated %}
13+
You're not viewing the latest released version.
14+
<a href="{{ '../' ~ base_url }}" class="md-content__link">
15+
<strong>Click here to go to latest.</strong>
16+
</a>
17+
{% endblock %}
18+
19+
{% block container %}
20+
<div class="md-content" data-md-component="content">
21+
{% include "partials/breadcrumb.html" %}
22+
<article class="md-content__inner md-typeset">
23+
{% block content %}
24+
{% include "partials/content.html" %}
25+
{% endblock %}
26+
</article>
27+
</div>
28+
{% endblock %}

‎docs/overrides/partials/breadcrumb.html‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{% macro render_breadcrumbs(nav_items, path=[]) %}
2+
{% for item in nav_items %}
3+
{% set new_path = path + [item] %}
4+
{% if item.children %}
5+
{{ render_breadcrumbs(item.children, new_path) }}
6+
{% elif item.url == page.url %}
7+
{% if new_path | length > 1 %}
8+
<nav class="md-path">
9+
<ol class="md-path__list">
10+
{% for crumb in new_path[:-1] %}
11+
<li class="md-path__item">
12+
{# Ensure link is absolute relative to the root #}
13+
<a href="{{ crumb.url | url }}" class="md-path__link">
14+
<span class="md-ellipsis">{{ crumb.title }}</span>
15+
</a>
16+
</li>
17+
{% endfor %}
18+
</ol>
19+
</nav>
20+
{% endif %}
21+
{% endif %}
22+
{% endfor %}
23+
{% endmacro %}
24+
25+
{{ render_breadcrumbs(nav) }}

0 commit comments

Comments
 (0)