Skip to content

Commit 6e52ea1

Browse files
dhuzarddhuzard
committed
Add assembly galleries to Sphinx tutorials
1 parent 89aaecb commit 6e52ea1

33 files changed

Lines changed: 210 additions & 65 deletions

‎docs/source/_ext/assembly_videos.py‎

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
"""Attach temporary assembly-video players to the matching tutorial pages."""
1+
"""Attach assembly videos and reference galleries to module tutorial pages."""
22

33
from __future__ import annotations
44

@@ -42,6 +42,61 @@
4242
}
4343

4444

45+
GALLERIES = {
46+
"build/assembly-tutorials/modules/mod-frm-assembly": [
47+
("/images/BB_V3_Material.jpg", "BEATBox V3 parts prepared for assembly", "V3 parts and materials"),
48+
("/images/real-build-setup.jpg", "BEATBox enclosure during assembly", "Enclosure assembly"),
49+
("/images/BB_Full-1.jpg", "Completed BEATBox viewed from the front", "Completed enclosure — front"),
50+
("/images/BB_Full-2.jpg", "Completed BEATBox viewed from the side", "Completed enclosure — side"),
51+
],
52+
"build/assembly-tutorials/modules/mod-bmt-assembly": [
53+
("/images/BB-TIPS_Using-forceps-to-help-inserts.jpg", "Using forceps to position a threaded insert", "Positioning threaded inserts"),
54+
("/images/BB_water-holder.jpg", "Completed BEATBox water bottle holder", "Completed water bottle mount"),
55+
],
56+
"build/assembly-tutorials/modules/mod-fdr-aseembly": [
57+
("/videos/buidling_gifs/BB_Feeder_material.tiny.gif", "Feeder parts laid out before assembly", "Prepare the feeder parts"),
58+
("/images/Feeder/BB_Feeder-1.jpg", "First stage of the feeder housing assembly", "Prepare the housing — 1"),
59+
("/images/Feeder/BB_Feeder-2.jpg", "Second stage of the feeder housing assembly", "Prepare the housing — 2"),
60+
("/images/Feeder/BB_Feeder_IR-1.jpg", "First stage of feeder IR board installation", "Install the IR board — 1"),
61+
("/images/Feeder/BB_Feeder_IR-2.jpg", "Second stage of feeder IR board installation", "Install the IR board — 2"),
62+
("/images/Feeder/BB_Feeder_IR-3.jpg", "Third stage of feeder IR board installation", "Install the IR board — 3"),
63+
("/images/Feeder/BB_Feeder_IR-4.jpg", "Fourth stage of feeder IR board installation", "Install the IR board — 4"),
64+
("/images/Feeder/BB_Feeder_IR-5.jpg", "Fifth stage of feeder IR board installation", "Install the IR board — 5"),
65+
("/images/Feeder/BB_Feeder_cable.jpg", "Feeder cable routed through the housing", "Route the IR cable"),
66+
("/videos/buidling_gifs/BB_Feeder-motor.tiny.gif", "Feeder stepper motor installation", "Install the stepper motor"),
67+
("/images/Feeder/BB_Feeder_PCB_color-code.jpg", "Feeder PCB terminal wire color reference", "Connect the motor wires"),
68+
("/videos/buidling_gifs/BB_Feeder-Assembly-motor-cables-to-PCB.tiny.gif", "Connecting the feeder motor cables to the PCB", "Wire the motor to the PCB"),
69+
("/images/Feeder.jpg", "Completed BEATBox feeder viewed from the front", "Completed feeder — front"),
70+
("/images/Feeder_side.jpg", "Completed BEATBox feeder viewed from the side", "Completed feeder — side"),
71+
],
72+
"build/assembly-tutorials/modules/mod-lgt": [
73+
("/images/Light_bottom.jpg", "Bottom face of the assembled BEATBox light ring", "PCB, housing, and connector"),
74+
("/images/Light_top.jpg", "Top face of the assembled BEATBox light ring", "Completed light ring and diffuser"),
75+
],
76+
"build/assembly-tutorials/modules/mod-pbg-assembly": [
77+
("/images/Tunnel-Passage-Corridor/BB_Tunnel_PCB.jpg", "Photobeam gate controller and IR circuit boards", "Prepare the electronics"),
78+
("/images/Tunnel-Passage-Corridor/BB_Tunnel_IR-PCG-with-cables.jpg", "Photobeam gate IR boards connected with cables", "Connect the IR boards"),
79+
("/images/Tunnel-Passage-Corridor/BB_Tunnel_PCG-assembly.jpg", "Circuit boards being installed in the photobeam passage", "Install and route the electronics"),
80+
("/images/Tunnel-Passage-Corridor/BB_Tunnel_PCG-assembled.jpg", "Assembled photobeam gate electronics", "Check the assembled electronics"),
81+
("/images/Tunnel.jpg", "Completed BEATBox photobeam gate", "Completed photobeam gate"),
82+
],
83+
"build/assembly-tutorials/modules/mod-scr-assembly": [
84+
("/images/Screens/BB_Screen-1.jpg", "First stage of BEATBox screen module assembly", "Screen assembly — 1"),
85+
("/images/Screens/BB_Screen-2.jpg", "Second stage of BEATBox screen module assembly", "Screen assembly — 2"),
86+
("/images/Screens/BB_Screen-3.jpg", "Third stage of BEATBox screen module assembly", "Screen assembly — 3"),
87+
("/images/Screens/BB_Screen-4.jpg", "Fourth stage of BEATBox screen module assembly", "Screen assembly — 4"),
88+
("/images/Screens/BB_Screen-5.jpg", "Fifth stage of BEATBox screen module assembly", "Screen assembly — 5"),
89+
("/images/Screens/BB_Screen-6.jpg", "Sixth stage of BEATBox screen module assembly", "Screen assembly — 6"),
90+
("/images/Screens/BB_Screen_inside.jpg", "Interior of the BEATBox screen module", "Interior layout"),
91+
("/images/Screens/BB_Screen_long-cables.jpg", "Long cables routed inside the BEATBox screen module", "Cable routing"),
92+
("/images/Screens/BB_Screens-inside-view.jpg", "First inside view of the assembled screen module", "Inside view — 1"),
93+
("/images/Screens/BB_Screens_Inside-view-2.jpg", "Second inside view of the assembled screen module", "Inside view — 2"),
94+
("/images/electronics/photo-circuit-ecrans1.jpg", "First screen electronics connection reference", "Screen electronics — 1"),
95+
("/images/electronics/photo-circuit-ecrans2.jpg", "Second screen electronics connection reference", "Screen electronics — 2"),
96+
],
97+
}
98+
99+
45100
def _append_video(app: Sphinx, doctree: nodes.document, docname: str) -> None:
46101
video = VIDEOS.get(docname)
47102
if video is None or app.builder.format != "html":
@@ -95,8 +150,44 @@ def _append_video(app: Sphinx, doctree: nodes.document, docname: str) -> None:
95150
doctree += section
96151

97152

153+
def _append_gallery(app: Sphinx, doctree: nodes.document, docname: str) -> None:
154+
gallery = GALLERIES.get(docname)
155+
if gallery is None or app.builder.format != "html":
156+
return
157+
158+
section = nodes.section(ids=["assembly-gallery"])
159+
section += nodes.title(text="Assembly gallery")
160+
section += nodes.paragraph(
161+
text=(
162+
"Use these reference images alongside the numbered instructions above. "
163+
"They are ordered to follow the main stages of the assembly. Select an "
164+
"image to open the full-size version."
165+
)
166+
)
167+
168+
figures = []
169+
for image_url, alt_text, caption in gallery:
170+
escaped_url = escape(image_url, quote=True)
171+
figures.append(
172+
'<figure class="assembly-gallery-item">'
173+
f'<a href="{escaped_url}" target="_blank" rel="noopener noreferrer">'
174+
f'<img src="{escaped_url}" alt="{escape(alt_text, quote=True)}" loading="lazy">'
175+
"</a>"
176+
f"<figcaption>{escape(caption)}</figcaption>"
177+
"</figure>"
178+
)
179+
180+
section += nodes.raw(
181+
"",
182+
'<div class="assembly-gallery">' + "".join(figures) + "</div>",
183+
format="html",
184+
)
185+
doctree += section
186+
187+
98188
def setup(app: Sphinx) -> dict[str, object]:
99189
app.connect("doctree-resolved", _append_video)
190+
app.connect("doctree-resolved", _append_gallery)
100191
return {
101192
"version": "1.0",
102193
"parallel_read_safe": True,

‎docs/source/_static/custom.css‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,35 @@
1111
height: 100%;
1212
width: 100%;
1313
}
14+
15+
.assembly-gallery {
16+
display: grid;
17+
gap: 1rem;
18+
grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
19+
margin: 1rem 0;
20+
}
21+
22+
.assembly-gallery-item {
23+
background: var(--color-background-secondary);
24+
border: 1px solid var(--color-foreground-border);
25+
border-radius: 0.5rem;
26+
margin: 0;
27+
overflow: hidden;
28+
}
29+
30+
.assembly-gallery-item a {
31+
background: #fff;
32+
display: block;
33+
}
34+
35+
.assembly-gallery-item img {
36+
aspect-ratio: 4 / 3;
37+
display: block;
38+
object-fit: contain;
39+
width: 100%;
40+
}
41+
42+
.assembly-gallery-item figcaption {
43+
font-size: 0.9rem;
44+
padding: 0.65rem 0.8rem;
45+
}

‎docs/source/build/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Before you begin, read the safety notes and check that the bill of materials mat
66

77
```{toctree}
88
:maxdepth: 2
9+
:hidden:
910
1011
assembly
1112
bom

‎site/public/docs/manual/_sources/build/index.md.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Before you begin, read the safety notes and check that the bill of materials mat
66

77
```{toctree}
88
:maxdepth: 2
9+
:hidden:
910

1011
assembly
1112
bom

‎site/public/docs/manual/_static/custom.css‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,35 @@
1111
height: 100%;
1212
width: 100%;
1313
}
14+
15+
.assembly-gallery {
16+
display: grid;
17+
gap: 1rem;
18+
grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
19+
margin: 1rem 0;
20+
}
21+
22+
.assembly-gallery-item {
23+
background: var(--color-background-secondary);
24+
border: 1px solid var(--color-foreground-border);
25+
border-radius: 0.5rem;
26+
margin: 0;
27+
overflow: hidden;
28+
}
29+
30+
.assembly-gallery-item a {
31+
background: #fff;
32+
display: block;
33+
}
34+
35+
.assembly-gallery-item img {
36+
aspect-ratio: 4 / 3;
37+
display: block;
38+
object-fit: contain;
39+
width: 100%;
40+
}
41+
42+
.assembly-gallery-item figcaption {
43+
font-size: 0.9rem;
44+
padding: 0.65rem 0.8rem;
45+
}

‎site/public/docs/manual/build/assembly-tutorials/conventions.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=7bdb33bb" />
1313
<link rel="stylesheet" type="text/css" href="../../_static/sphinx-design.min.css?v=95c83b7e" />
1414
<link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?v=8dab3a3b" />
15-
<link rel="stylesheet" type="text/css" href="../../_static/custom.css?v=89552e2e" />
15+
<link rel="stylesheet" type="text/css" href="../../_static/custom.css?v=c5a0cfb3" />
1616

1717

1818

‎site/public/docs/manual/build/assembly-tutorials/modules/mod-bmt-assembly.html‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
<link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?v=7bdb33bb" />
1313
<link rel="stylesheet" type="text/css" href="../../../_static/sphinx-design.min.css?v=95c83b7e" />
1414
<link rel="stylesheet" type="text/css" href="../../../_static/styles/furo-extensions.css?v=8dab3a3b" />
15-
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css?v=89552e2e" />
15+
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css?v=c5a0cfb3" />
1616

1717

1818

@@ -388,6 +388,10 @@ <h1>Assembly video<a class="headerlink" href="#assembly-video-tutorial" title="L
388388
<p>Temporary hosting: this Drive player will be replaced by the project's YouTube stream after publication; the released original will be archived on Zenodo. Google may request sign-in until public sharing is confirmed.</p>
389389
</div>
390390
</section>
391+
<section id="assembly-gallery">
392+
<h1>Assembly gallery<a class="headerlink" href="#assembly-gallery" title="Link to this heading"></a></h1>
393+
<p>Use these reference images alongside the numbered instructions above. They are ordered to follow the main stages of the assembly. Select an image to open the full-size version.</p>
394+
<div class="assembly-gallery"><figure class="assembly-gallery-item"><a href="/images/BB-TIPS_Using-forceps-to-help-inserts.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/BB-TIPS_Using-forceps-to-help-inserts.jpg" alt="Using forceps to position a threaded insert" loading="lazy"></a><figcaption>Positioning threaded inserts</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/BB_water-holder.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/BB_water-holder.jpg" alt="Completed BEATBox water bottle holder" loading="lazy"></a><figcaption>Completed water bottle mount</figcaption></figure></div></section>
391395

392396
</article>
393397
</div>

‎site/public/docs/manual/build/assembly-tutorials/modules/mod-fdr-aseembly.html‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
<link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?v=7bdb33bb" />
1313
<link rel="stylesheet" type="text/css" href="../../../_static/sphinx-design.min.css?v=95c83b7e" />
1414
<link rel="stylesheet" type="text/css" href="../../../_static/styles/furo-extensions.css?v=8dab3a3b" />
15-
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css?v=89552e2e" />
15+
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css?v=c5a0cfb3" />
1616

1717

1818

@@ -488,6 +488,10 @@ <h1>Assembly video<a class="headerlink" href="#assembly-video-tutorial" title="L
488488
<p>Temporary hosting: this Drive player will be replaced by the project's YouTube stream after publication; the released original will be archived on Zenodo. Google may request sign-in until public sharing is confirmed.</p>
489489
</div>
490490
</section>
491+
<section id="assembly-gallery">
492+
<h1>Assembly gallery<a class="headerlink" href="#assembly-gallery" title="Link to this heading"></a></h1>
493+
<p>Use these reference images alongside the numbered instructions above. They are ordered to follow the main stages of the assembly. Select an image to open the full-size version.</p>
494+
<div class="assembly-gallery"><figure class="assembly-gallery-item"><a href="/videos/buidling_gifs/BB_Feeder_material.tiny.gif" target="_blank" rel="noopener noreferrer"><img src="/videos/buidling_gifs/BB_Feeder_material.tiny.gif" alt="Feeder parts laid out before assembly" loading="lazy"></a><figcaption>Prepare the feeder parts</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder-1.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder-1.jpg" alt="First stage of the feeder housing assembly" loading="lazy"></a><figcaption>Prepare the housing — 1</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder-2.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder-2.jpg" alt="Second stage of the feeder housing assembly" loading="lazy"></a><figcaption>Prepare the housing — 2</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder_IR-1.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder_IR-1.jpg" alt="First stage of feeder IR board installation" loading="lazy"></a><figcaption>Install the IR board — 1</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder_IR-2.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder_IR-2.jpg" alt="Second stage of feeder IR board installation" loading="lazy"></a><figcaption>Install the IR board — 2</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder_IR-3.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder_IR-3.jpg" alt="Third stage of feeder IR board installation" loading="lazy"></a><figcaption>Install the IR board — 3</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder_IR-4.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder_IR-4.jpg" alt="Fourth stage of feeder IR board installation" loading="lazy"></a><figcaption>Install the IR board — 4</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder_IR-5.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder_IR-5.jpg" alt="Fifth stage of feeder IR board installation" loading="lazy"></a><figcaption>Install the IR board — 5</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder_cable.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder_cable.jpg" alt="Feeder cable routed through the housing" loading="lazy"></a><figcaption>Route the IR cable</figcaption></figure><figure class="assembly-gallery-item"><a href="/videos/buidling_gifs/BB_Feeder-motor.tiny.gif" target="_blank" rel="noopener noreferrer"><img src="/videos/buidling_gifs/BB_Feeder-motor.tiny.gif" alt="Feeder stepper motor installation" loading="lazy"></a><figcaption>Install the stepper motor</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder/BB_Feeder_PCB_color-code.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder/BB_Feeder_PCB_color-code.jpg" alt="Feeder PCB terminal wire color reference" loading="lazy"></a><figcaption>Connect the motor wires</figcaption></figure><figure class="assembly-gallery-item"><a href="/videos/buidling_gifs/BB_Feeder-Assembly-motor-cables-to-PCB.tiny.gif" target="_blank" rel="noopener noreferrer"><img src="/videos/buidling_gifs/BB_Feeder-Assembly-motor-cables-to-PCB.tiny.gif" alt="Connecting the feeder motor cables to the PCB" loading="lazy"></a><figcaption>Wire the motor to the PCB</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder.jpg" alt="Completed BEATBox feeder viewed from the front" loading="lazy"></a><figcaption>Completed feeder — front</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/Feeder_side.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/Feeder_side.jpg" alt="Completed BEATBox feeder viewed from the side" loading="lazy"></a><figcaption>Completed feeder — side</figcaption></figure></div></section>
491495

492496
</article>
493497
</div>

‎site/public/docs/manual/build/assembly-tutorials/modules/mod-frm-assembly.html‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
<link rel="stylesheet" type="text/css" href="../../../_static/styles/furo.css?v=7bdb33bb" />
1313
<link rel="stylesheet" type="text/css" href="../../../_static/sphinx-design.min.css?v=95c83b7e" />
1414
<link rel="stylesheet" type="text/css" href="../../../_static/styles/furo-extensions.css?v=8dab3a3b" />
15-
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css?v=89552e2e" />
15+
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css?v=c5a0cfb3" />
1616

1717

1818

@@ -593,6 +593,10 @@ <h1>Assembly video<a class="headerlink" href="#assembly-video-tutorial" title="L
593593
<p>Temporary hosting: this Drive player will be replaced by the project's YouTube stream after publication; the released original will be archived on Zenodo. Google may request sign-in until public sharing is confirmed.</p>
594594
</div>
595595
</section>
596+
<section id="assembly-gallery">
597+
<h1>Assembly gallery<a class="headerlink" href="#assembly-gallery" title="Link to this heading"></a></h1>
598+
<p>Use these reference images alongside the numbered instructions above. They are ordered to follow the main stages of the assembly. Select an image to open the full-size version.</p>
599+
<div class="assembly-gallery"><figure class="assembly-gallery-item"><a href="/images/BB_V3_Material.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/BB_V3_Material.jpg" alt="BEATBox V3 parts prepared for assembly" loading="lazy"></a><figcaption>V3 parts and materials</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/real-build-setup.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/real-build-setup.jpg" alt="BEATBox enclosure during assembly" loading="lazy"></a><figcaption>Enclosure assembly</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/BB_Full-1.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/BB_Full-1.jpg" alt="Completed BEATBox viewed from the front" loading="lazy"></a><figcaption>Completed enclosure — front</figcaption></figure><figure class="assembly-gallery-item"><a href="/images/BB_Full-2.jpg" target="_blank" rel="noopener noreferrer"><img src="/images/BB_Full-2.jpg" alt="Completed BEATBox viewed from the side" loading="lazy"></a><figcaption>Completed enclosure — side</figcaption></figure></div></section>
596600

597601
</article>
598602
</div>

0 commit comments

Comments
 (0)