Skip to content

Commit 6b8a975

Browse files
robinhundtrobinhundt
authored
Merge pull request #273 from sine-fdn/fix/garble-docs
Fix garble_docs
2 parents ac3ad4e + a93e08d commit 6b8a975

File tree

6 files changed

+350
-187
lines changed

6 files changed

+350
-187
lines changed

.github/workflows/pages.yml renamed to .github/workflows/deploy_pages.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
- uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9
1919
with:
2020
toolchain: stable
21-
- name: Install taplo for extracting polytune version
21+
- name: Install mdBook
2222
uses: taiki-e/install-action@537c30d2b45cc3aa3fb35e2bbcfb61ef93fd6f02
2323
# if updating install-action, check if there is a new mdbook release
2424
with:

‎.github/workflows/test_pages.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Test Mdbook Pages
2+
on:
3+
push:
4+
paths:
5+
- 'garble_docs/**'
6+
- '.github/workflows/deploy_pages.yml'
7+
- '.github/workflows/test_pages.yml'
8+
9+
jobs:
10+
test-mdbook:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3
14+
- uses: dtolnay/rust-toolchain@e97e2d8cc328f1b50210efc529dca0028893a2d9
15+
with:
16+
toolchain: stable
17+
- name: Install mdBook
18+
uses: taiki-e/install-action@537c30d2b45cc3aa3fb35e2bbcfb61ef93fd6f02
19+
# if updating install-action, check if there is a new mdbook release
20+
with:
21+
tool: mdbook@0.5.1
22+
- name: Build Book
23+
run: |
24+
cd garble_docs && mdbook build

‎garble_docs/book.toml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
[book]
2-
authors = ["Frederic Kettelhoit"]
2+
authors = ["Frederic Kettelhoit", "Robin Hundt"]
33
language = "en"
4-
multilingual = false
54
src = "src"
65
title = "The Garble Programming Language"
6+
77
[output.html]
88
no-section-label = true
9+
git-repository-url = "https://github.com/sine-fdn/garble-lang"
10+
911
[output.html.playground]
1012
runnable = false

‎garble_docs/src/contributing.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
# Contributing
22

3-
While Garble was developed by us at the [SINE Foundation](https://sine.foundation/) for the use in our MPC engine, we would love to see how you end up using Garble and are happy to accept pull requests. Garble is distributed under the MIT license and hosted on GitHub:
4-
5-
[![Github](github-mark.png "Contribute on Github")](https://github.com/sine-fdn/garble-lang)
3+
While Garble was developed by us at the [SINE Foundation](https://sine.foundation/) for the use in our MPC engine, we would love to see how you end up using Garble and are happy to accept pull requests. Garble is distributed under the MIT license and
4+
<a href="https://github.com/sine-fdn/garble-lang">
5+
hosted on GitHub
6+
<img src="github-mark.png" alt="Github" title="Contribute on Github" width="16" height="16">.
7+
</a>
68

79
The Garble compiler is relatively straightforward and turns a program `&str` into a `circuit::Circuit` (or aborts with a scan/parse/type error). The different steps and their modules are as follows (with steps 1-4 happening during compile time, step 5 is optional and happens during run time):
810

‎garble_docs/theme/css/general.css‎

Lines changed: 165 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,8 @@ h2:target::before,
8787
h3:target::before,
8888
h4:target::before,
8989
h5:target::before,
90-
h6:target::before {
90+
h6:target::before,
91+
dt:target::before {
9192
display: inline-block;
9293
content: "»";
9394
margin-inline-start: -30px;
@@ -107,21 +108,22 @@ h6:target::before {
107108
outline: 0;
108109
padding: 0 var(--page-padding);
109110
margin-block-start: calc(0px - var(--menu-bar-height));
110-
/* Compensate for the #menu-bar-hover-placeholder */
111+
/* Compensate for the #mdbook-menu-bar-hover-placeholder */
111112
}
112113

113114
.page-wrapper {
114115
box-sizing: border-box;
115116
background-color: var(--bg);
116117
}
117118

118-
.no-js .page-wrapper,
119+
html:not(.js) .page-wrapper,
119120
.js:not(.sidebar-resizing) .page-wrapper {
120121
transition: margin-left 0.3s ease, transform 0.3s ease;
121122
/* Animation: slide away */
122123
}
123124

124-
[dir=rtl] .js:not(.sidebar-resizing) .page-wrapper {
125+
[dir=rtl]:not(.js) .page-wrapper,
126+
[dir=rtl].js:not(.sidebar-resizing) .page-wrapper {
125127
transition: margin-right 0.3s ease, transform 0.3s ease;
126128
/* Animation: slide away */
127129
}
@@ -214,6 +216,8 @@ blockquote {
214216
border-block-end: .1em solid var(--quote-border);
215217
}
216218

219+
/* TODO: Remove .warning in a future version of mdbook, it is replaced by
220+
blockquote tags. */
217221
.warning {
218222
margin: 20px;
219223
padding: 0 20px;
@@ -260,18 +264,59 @@ sup {
260264
line-height: 0;
261265
}
262266

263-
:not(.footnote-definition)+.footnote-definition,
264-
.footnote-definition+ :not(.footnote-definition) {
265-
margin-block-start: 2em;
266-
}
267-
268267
.footnote-definition {
269268
font-size: 0.9em;
270-
margin: 0.5em 0;
271269
}
272270

273-
.footnote-definition p {
274-
display: inline;
271+
/* The default spacing for a list is a little too large. */
272+
.footnote-definition ul,
273+
.footnote-definition ol {
274+
padding-left: 20px;
275+
}
276+
277+
.footnote-definition>li {
278+
/* Required to position the ::before target */
279+
position: relative;
280+
}
281+
282+
.footnote-definition>li:target {
283+
scroll-margin-top: 50vh;
284+
}
285+
286+
.footnote-reference:target {
287+
scroll-margin-top: 50vh;
288+
}
289+
290+
/* Draws a border around the footnote (including the marker) when it is selected.
291+
TODO: If there are multiple linkbacks, highlight which one you just came
292+
from so you know which one to click.
293+
*/
294+
.footnote-definition>li:target::before {
295+
border: 2px solid var(--footnote-highlight);
296+
border-radius: 6px;
297+
position: absolute;
298+
top: -8px;
299+
right: -8px;
300+
bottom: -8px;
301+
left: -32px;
302+
pointer-events: none;
303+
content: "";
304+
}
305+
306+
/* Pulses the footnote reference so you can quickly see where you left off reading.
307+
This could use some improvement.
308+
*/
309+
@media not (prefers-reduced-motion) {
310+
.footnote-reference:target {
311+
animation: fn-highlight 0.8s;
312+
border-radius: 2px;
313+
}
314+
315+
@keyframes fn-highlight {
316+
from {
317+
background-color: var(--footnote-highlight);
318+
}
319+
}
275320
}
276321

277322
.tooltiptext {
@@ -306,102 +351,150 @@ sup {
306351
font-style: italic;
307352
}
308353

309-
/* Customizations */
354+
.fa-svg svg {
355+
width: 1em;
356+
height: 1em;
357+
fill: currentColor;
358+
margin-bottom: -0.1em;
359+
}
310360

311-
#menu-bar,
312-
#sidebar-resize-handle {
313-
display: none !important;
361+
dt {
362+
font-weight: bold;
363+
margin-top: 0.5em;
364+
margin-bottom: 0.1em;
365+
}
366+
367+
/* This uses a CSS counter to add numbers to definitions, but only if there is
368+
more than one definition. */
369+
dl,
370+
dt {
371+
counter-reset: dd-counter;
372+
}
373+
374+
/* When there is more than one definition, increment the counter. The first
375+
selector selects the first definition, and the second one selects definitions
376+
2 and beyond.*/
377+
dd:has(+ dd),
378+
dd+dd {
379+
counter-increment: dd-counter;
380+
/* Use flex display to help with positioning the numbers when there is a p
381+
tag inside the definition. */
382+
display: flex;
383+
align-items: flex-start;
384+
}
385+
386+
/* Shows the counter for definitions. The first selector selects the first
387+
definition, and the second one selections definitions 2 and beyond.*/
388+
dd:has(+ dd)::before,
389+
dd+dd::before {
390+
content: counter(dd-counter) ". ";
391+
font-weight: 600;
392+
display: inline-block;
393+
margin-right: 0.5em;
314394
}
315395

316-
#sidebar {
317-
background-color: inherit !important;
396+
dd>p {
397+
/* For loose definitions that have a p tag inside, don't add a bunch of
398+
space before the definition. */
399+
margin-top: 0;
318400
}
319401

320-
mdbook-sidebar-scrollbox {
321-
margin-top: 12em !important;
322-
padding-top: 0 !important;
323-
padding-left: 5em !important;
402+
/* Remove some excess space from the bottom. */
403+
.blockquote-tag p:last-child {
404+
margin-bottom: 2px;
324405
}
325406

326-
h1 {
327-
margin-top: 2em !important;
407+
.blockquote-tag {
408+
/* Add some padding to make the vertical bar a little taller than the text.*/
409+
padding: 2px 0px 2px 20px;
410+
/* Add a solid color bar on the left side. */
411+
border-inline-start-style: solid;
412+
border-inline-start-width: 4px;
413+
/* Disable the background color from normal blockquotes . */
414+
background-color: inherit;
415+
/* Disable border blocks from blockquotes. */
416+
border-block-start: none;
417+
border-block-end: none;
328418
}
329419

330-
.sine-logo {
331-
display: inline-block;
332-
padding-top: 5em;
333-
padding-left: 4.5em;
420+
.blockquote-tag-title svg {
421+
fill: currentColor;
422+
/* Add space between the icon and the title. */
423+
margin-right: 8px;
334424
}
335425

336-
* {
337-
font-family: Avenir, Montserrat, Corbel, 'URW Gothic', source-sans-pro, sans-serif;
426+
.blockquote-tag-note {
427+
border-inline-start-color: var(--blockquote-note-color);
338428
}
339429

340-
code,
341-
code * {
342-
font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace !important;
430+
.blockquote-tag-tip {
431+
border-inline-start-color: var(--blockquote-tip-color);
343432
}
344433

345-
:not(pre):not(a)>code.hljs {
346-
color: #222;
434+
.blockquote-tag-important {
435+
border-inline-start-color: var(--blockquote-important-color);
347436
}
348437

349-
:not(pre)>code.hljs {
350-
background-color: #eee;
438+
.blockquote-tag-warning {
439+
border-inline-start-color: var(--blockquote-warning-color);
351440
}
352441

353-
p {
354-
line-height: 1.6em !important;
355-
margin-block-start: 1.6em;
356-
margin-block-end: 1.6em;
442+
.blockquote-tag-caution {
443+
border-inline-start-color: var(--blockquote-caution-color);
357444
}
358445

359-
img[alt=Github] {
360-
width: 80px;
446+
.blockquote-tag-note .blockquote-tag-title {
447+
color: var(--blockquote-note-color);
361448
}
362449

363-
a,
364-
#sidebar a.active {
365-
font-weight: bold;
450+
.blockquote-tag-tip .blockquote-tag-title {
451+
color: var(--blockquote-tip-color);
366452
}
367453

368-
#sidebar a {
369-
font-weight: normal;
454+
.blockquote-tag-important .blockquote-tag-title {
455+
color: var(--blockquote-important-color);
370456
}
371457

372-
.abnf,
373-
.abnf>* {
374-
font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace !important;
375-
line-height: 1.8;
458+
.blockquote-tag-warning .blockquote-tag-title {
459+
color: var(--blockquote-warning-color);
376460
}
377461

378-
.abnf .str {
379-
display: inline;
380-
padding: 0.1em 0.3em;
381-
border-radius: 3px;
382-
border: 1px solid #333;
383-
background-color: #666;
384-
line-height: 1.8;
462+
.blockquote-tag-caution .blockquote-tag-title {
463+
color: var(--blockquote-caution-color);
385464
}
386465

387-
.table-wrapper {
388-
overflow-x: auto;
466+
.blockquote-tag-title {
467+
/* Slightly increase the weight for more emphasis. */
468+
font-weight: 600;
469+
/* Vertically center the icon with the text. */
470+
display: flex;
471+
align-items: center;
472+
/* Remove default large margins for a more compact display. */
473+
margin: 2px 0 8px 0;
389474
}
390475

391-
table {
392-
margin: 0;
393-
border: none;
476+
.blockquote-tag-title .fa-svg {
477+
fill: currentColor;
478+
/* Add some space between the icon and the text. */
479+
margin-right: 8px;
394480
}
395481

396-
table tbody tr:nth-child(2n) {
397-
background-color: unset !important;
482+
483+
484+
/************* Our own additions *************/
485+
486+
.sine-logo {
487+
display: inline-block;
488+
padding-top: 5em;
489+
padding-left: 4.5em;
398490
}
399491

400-
table thead th {
401-
text-align: left;
402-
padding: 6px 6px;
492+
#mdbook-sidebar {
493+
background-color: inherit !important;
403494
}
404495

405-
table td {
406-
padding: 6px 4px;
407-
}
496+
mdbook-sidebar-scrollbox {
497+
margin-top: 12em !important;
498+
padding-top: 0 !important;
499+
padding-left: 5em !important;
500+
}

0 commit comments

Comments
 (0)