Skip to content

Commit 75813a5

Browse files
philipstarkeyphilipstarkey
committed
Updated PR as per review in labscript-suite/labscript-suite#48 
1 parent 573c521 commit 75813a5

14 files changed

+1963
-146
lines changed

‎.gitignore

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
# This gitignore file consists of 2 parts:
2+
# * The standard Python .gitignore rules from GitHub
3+
# * custom ignore rules for the labscript suite.
4+
#
5+
# These should be kept separate so that the generic rules can be updated with a
6+
# copy/paste without having to worry about whether we are removing custom rules
7+
18
# Byte-compiled / optimized / DLL files
29
__pycache__/
310
*.py[cod]
@@ -130,6 +137,10 @@ dmypy.json
130137
# Pyre type checker
131138
.pyre/
132139

140+
#
141+
# Custom labscript suite .gitignore rules start below
142+
#
143+
133144
# Editors
134145
.vscode/
135146

‎docs/source/_static/custom.css

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,7 @@ details {
5757
0px 8px 10px 1px rgba(0, 0, 0, 0.14), 0px 3px 14px 2px rgba(0, 0, 0, 0.12);
5858
margin-bottom: 24px;
5959
}
60+
61+
img.labscript-suite-icon {
62+
min-width: 32px;
63+
}

‎docs/source/components.rst

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
2+
.. toctree::
3+
:maxdepth: 2
4+
:hidden:
5+
6+
Metapackage documentation <https://docs.labscriptsuite.org/en/latest/>
7+
8+
9+
*labscript suite* components
10+
============================
11+
12+
The *labscript suite* is modular by design, and is comprised of:
13+
14+
.. list-table:: Python libraries
15+
:widths: 10 90
16+
:header-rows: 0
17+
18+
* - .. image:: img/labscript_32nx32n.svg
19+
:target: https://docs.labscriptsuite.org/projects/labscript/en/latest/
20+
:class: labscript-suite-icon
21+
- |labscript|_ --- Expressive composition of hardware-timed experiments
22+
* - .. image:: img/labscript_32nx32n.svg
23+
:target: https://docs.labscriptsuite.org/projects/labscript-devices/en/latest/
24+
:class: labscript-suite-icon
25+
- |labscript-devices|_ --- Plugin architecture for controlling experiment hardware
26+
* - .. image:: img/labscript_32nx32n.svg
27+
:target: https://docs.labscriptsuite.org/projects/labscript-utils/en/latest/
28+
:class: labscript-suite-icon
29+
- |labscript-utils|_ --- Shared modules used by the *labscript suite*
30+
31+
32+
.. list-table:: Graphical applications
33+
:widths: 10 90
34+
:header-rows: 0
35+
36+
* - .. image:: img/runmanager_32nx32n.svg
37+
:target: https://docs.labscriptsuite.org/projects/runmanager/en/latest/
38+
:class: labscript-suite-icon
39+
- |runmanager|_ --- Graphical and remote interface to parameterized experiments
40+
* - .. image:: img/blacs_32nx32n.svg
41+
:target: https://docs.labscriptsuite.org/projects/blacs/en/latest/
42+
:class: labscript-suite-icon
43+
- |blacs|_ --- Graphical interface to scientific instruments and experiment supervision
44+
* - .. image:: img/lyse_32nx32n.svg
45+
:target: https://docs.labscriptsuite.org/projects/lyse/en/latest/
46+
:class: labscript-suite-icon
47+
- |lyse|_ --- Online analysis of live experiment data
48+
* - .. image:: img/runviewer_32nx32n.svg
49+
:target: https://docs.labscriptsuite.org/projects/runviewer/en/latest/
50+
:class: labscript-suite-icon
51+
- |runviewer|_ --- Visualize hardware-timed experiment instructions
52+
53+
54+
.. toctree::
55+
:maxdepth: 2
56+
:hidden:
57+
58+
blacs <https://docs.labscriptsuite.org/projects/blacs/en/latest/>
59+
labscript <https://docs.labscriptsuite.org/projects/labscript/en/latest/>
60+
labscript-devices <https://docs.labscriptsuite.org/projects/labscript-devices/en/latest/>
61+
lyse <https://docs.labscriptsuite.org/projects/lyse/en/latest/>
62+
runmanager <https://docs.labscriptsuite.org/projects/runmanager/en/latest/>
63+
runviewer <https://docs.labscriptsuite.org/projects/runviewer/en/latest/>
64+
65+
66+
.. |labscript| replace:: **labscript**
67+
.. _labscript: https://docs.labscriptsuite.org/projects/labscript/en/latest/
68+
.. |labscript-devices| replace:: **labscript-devices**
69+
.. _labscript-devices: https://docs.labscriptsuite.org/projects/labscript-devices/en/latest/
70+
.. |labscript-utils| replace:: **labscript-utils**
71+
.. _labscript-utils: https://docs.labscriptsuite.org/projects/labscript-utils/en/latest/
72+
.. |runmanager| replace:: **runmanager**
73+
.. _runmanager: https://docs.labscriptsuite.org/projects/runmanager/en/latest/
74+
.. |blacs| replace:: **blacs**
75+
.. _blacs: https://docs.labscriptsuite.org/projects/blacs/en/latest/
76+
.. |lyse| replace:: **lyse**
77+
.. _lyse: https://docs.labscriptsuite.org/projects/lyse/en/latest/
78+
.. |runviewer| replace:: **runviewer**
79+
.. _runviewer: https://docs.labscriptsuite.org/projects/runviewer/en/latest/
80+

‎docs/source/conf.py

Lines changed: 136 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
# documentation root, use os.path.abspath to make it absolute, like shown here.
1212
#
1313
import os
14+
from pathlib import Path
1415
from m2r import MdInclude
1516
from recommonmark.transform import AutoStructify
1617

@@ -26,8 +27,9 @@
2627
release = version
2728

2829
# HTML icons
29-
html_logo = "img/{}.svg".format(project)
30-
html_favicon = "img/{}.ico".format(project)
30+
img_path = 'img'
31+
html_logo = img_path + "/labscript_64x64.svg"
32+
html_favicon = img_path + "/labscript.ico"
3133

3234
# -- General configuration (should be identical across all projects) ------------------
3335

@@ -90,18 +92,43 @@
9092
}
9193

9294
# list of all labscript suite components that have docs
93-
labscript_suite_programs = [
94-
'labscript',
95-
'runmanager',
96-
'runviewer',
97-
'blacs',
98-
'lyse',
99-
'labscript-utils',
100-
'labscript-devices',
101-
]
102-
# remove this current repo from the list
103-
if project in labscript_suite_programs:
104-
labscript_suite_programs.remove(project)
95+
labscript_suite_programs = {
96+
'labscript': {
97+
'desc': 'Expressive composition of hardware-timed experiments',
98+
'img': img_path + '/labscript_32nx32n.svg',
99+
'type': 'lib',
100+
},
101+
'labscript-devices': {
102+
'desc': 'Plugin architecture for controlling experiment hardware',
103+
'img': img_path + '/labscript_32nx32n.svg',
104+
'type': 'lib',
105+
},
106+
'labscript-utils': {
107+
'desc': 'Shared modules used by the *labscript suite*',
108+
'img': img_path + '/labscript_32nx32n.svg',
109+
'type': 'lib',
110+
},
111+
'runmanager': {
112+
'desc': 'Graphical and remote interface to parameterized experiments',
113+
'img': img_path + '/runmanager_32nx32n.svg',
114+
'type': 'gui',
115+
},
116+
'blacs': {
117+
'desc': 'Graphical interface to scientific instruments and experiment supervision',
118+
'img': img_path + '/blacs_32nx32n.svg',
119+
'type': 'gui',
120+
},
121+
'lyse': {
122+
'desc': 'Online analysis of live experiment data',
123+
'img': img_path + '/lyse_32nx32n.svg',
124+
'type': 'gui',
125+
},
126+
'runviewer': {
127+
'desc': 'Visualize hardware-timed experiment instructions',
128+
'img': img_path + '/runviewer_32nx32n.svg',
129+
'type': 'gui',
130+
},
131+
}
105132

106133
# whether to use stable or latest version
107134
labscript_suite_doc_version = os.environ.get('READTHEDOCS_VERSION', 'latest')
@@ -111,7 +138,7 @@
111138
# add intersphinx references for each component
112139
for ls_prog in labscript_suite_programs:
113140
intersphinx_mapping[ls_prog] = (
114-
'https://docs.labscript_suite.org/projects/{}/en/{}/'.format(
141+
'https://docs.labscriptsuite.org/projects/{}/en/{}/'.format(
115142
ls_prog, labscript_suite_doc_version
116143
),
117144
None,
@@ -120,7 +147,7 @@
120147
# add intersphinx reference for the metapackage
121148
if project != "the labscript suite":
122149
intersphinx_mapping['labscript-suite'] = (
123-
'https://docs.labscript_suite.org/en/{}/'.format(labscript_suite_doc_version),
150+
'https://docs.labscriptsuite.org/en/{}/'.format(labscript_suite_doc_version),
124151
None,
125152
)
126153

@@ -160,6 +187,58 @@
160187
# Customize the html_theme
161188
html_theme_options = {'navigation_depth': 3}
162189

190+
# Template for generating the components.rst file
191+
# fmt:off
192+
components_rst_template = \
193+
"""
194+
{metapackage_toctree}
195+
196+
*labscript suite* components
197+
============================
198+
199+
The *labscript suite* is modular by design, and is comprised of:
200+
201+
.. list-table:: Python libraries
202+
:widths: 10 90
203+
:header-rows: 0
204+
205+
{lib}
206+
207+
.. list-table:: Graphical applications
208+
:widths: 10 90
209+
:header-rows: 0
210+
211+
{gui}
212+
213+
.. toctree::
214+
:maxdepth: 2
215+
:hidden:
216+
217+
{toctree_entires}
218+
219+
{rst_defs}
220+
"""
221+
222+
components_rst_table_template = \
223+
""" * - .. image:: {img}
224+
:target: {target}
225+
:class: labscript-suite-icon
226+
- |{prog}|_ --- {desc}
227+
"""
228+
229+
components_rst_link_template = \
230+
""".. |{prog}| replace:: **{prog}**
231+
.. _{prog}: {target}
232+
"""
233+
234+
components_rst_metapackage_template = \
235+
""".. toctree::
236+
:maxdepth: 2
237+
:hidden:
238+
239+
Metapackage documentation <{}>
240+
"""
241+
# fmt:on
163242

164243
# Use m2r only for mdinclude and recommonmark for everything else
165244
# https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992
@@ -180,21 +259,45 @@ def setup(app):
180259
app.add_directive('mdinclude', MdInclude)
181260
app.add_stylesheet('custom.css')
182261

183-
with open(
184-
os.path.join(os.path.dirname(os.path.realpath(__file__)), 'component_docs.rst'),
185-
'w',
186-
) as f:
187-
f.write("labscript suite components\n")
188-
f.write("==========================\n")
189-
f.write(" \n")
190-
f.write(".. toctree::\n")
191-
f.write(" :maxdepth: 2\n")
192-
f.write(" \n")
193-
if project != "the labscript suite":
194-
f.write(
195-
" labscript suite (metapackage)<{}>\n".format(
196-
intersphinx_mapping['labscript-suite'][0]
197-
)
262+
# generate the components.rst file dynamically so it points to stable/latest
263+
# of subprojects correctly
264+
components_rst_table = {
265+
"lib": "",
266+
"gui": "",
267+
}
268+
components_rst_link = ""
269+
components_rst_toctree = ""
270+
components_rst_metapackage = ""
271+
if project != 'the labscript suite':
272+
components_rst_metapackage = components_rst_metapackage_template.format(
273+
intersphinx_mapping['labscript-suite'][0]
274+
)
275+
metapackage_img = img_path + "/labscript-suite-rectangular-transparent_138nx70n.svg"
276+
for ls_prog, data in labscript_suite_programs.items():
277+
components_rst_table[data['type']] += components_rst_table_template.format(
278+
prog=ls_prog,
279+
labscript_suite_doc_version=labscript_suite_doc_version,
280+
target=intersphinx_mapping[ls_prog][0],
281+
**data
282+
)
283+
components_rst_link += components_rst_link_template.format(
284+
prog=ls_prog,
285+
labscript_suite_doc_version=labscript_suite_doc_version,
286+
target=intersphinx_mapping[ls_prog][0],
287+
)
288+
for ls_prog in sorted(labscript_suite_programs):
289+
if ls_prog != project:
290+
components_rst_toctree += " {} <{}>\n".format(
291+
ls_prog, intersphinx_mapping[ls_prog][0]
198292
)
199-
for ls_prog in labscript_suite_programs:
200-
f.write(" {} <{}>\n".format(ls_prog, intersphinx_mapping[ls_prog][0]))
293+
294+
components_rst = components_rst_template.format(
295+
toctree_entires=components_rst_toctree,
296+
rst_defs=components_rst_link,
297+
labscript_suite_doc_version=labscript_suite_doc_version,
298+
metapackage_toctree=components_rst_metapackage,
299+
**components_rst_table
300+
)
301+
302+
with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f:
303+
f.write(components_rst)

0 commit comments

Comments
 (0)