-Shared modules used by the labscript suite. Includes a graphical exception handler, debug tools, configuration management, cross platform filepath conversions, unit conversions and custom GUI widgets.
+# the _labscript suite_ ยป labscript-utils
-(
-[view on Github](https://github.com/labscript-suite/labscript_utils)
-)
+### Shared modules used by the _labscript suite_
+[](https://github.com/labscript-suite/labscript-utils/actions)
+[](https://github.com/labscript-suite/labscript-utils/raw/master/LICENSE.txt)
+[](https://python.org)
+[](https://pypi.org/project/labscript-utils)
+[](https://anaconda.org/labscript-suite/labscript-utils)
+[](https://groups.google.com/forum/#!forum/labscriptsuite)
+
+
+Shared modules used by the [*labscript suite*](https://github.com/labscript-suite/labscript-suite). Includes a graphical exception handler, debug tools, configuration management, cross-platform filepath conversions, physical unit conversions and custom GUI widgets.
+
+
+## Installation
+
+labscript-utils is distributed as a Python package on [PyPI](https://pypi.org/user/labscript-suite) and [Anaconda Cloud](https://anaconda.org/labscript-suite), and should be installed with other components of the _labscript suite_. Please see the [installation guide](https://docs.labscriptsuite.org/en/latest/installation) for details.
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
index ad5c1a8..d766bfa 100644
--- a/docs/source/_static/custom.css
+++ b/docs/source/_static/custom.css
@@ -57,3 +57,7 @@ details {
0px 8px 10px 1px rgba(0, 0, 0, 0.14), 0px 3px 14px 2px rgba(0, 0, 0, 0.12);
margin-bottom: 24px;
}
+
+img.labscript-suite-icon {
+ min-width: 32px;
+}
\ No newline at end of file
diff --git a/docs/source/_templates/components.rst b/docs/source/_templates/components.rst
new file mode 100644
index 0000000..f966939
--- /dev/null
+++ b/docs/source/_templates/components.rst
@@ -0,0 +1,47 @@
+{% if current_project != 'the labscript suite' %}
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ the labscript suite <{{intersphinx_mapping['labscript-suite'][0]}}>
+
+{% endif %}
+*labscript suite* components
+============================
+
+The *labscript suite* is modular by design, and is comprised of:
+
+.. list-table:: Python libraries
+ :widths: 10 90
+ :header-rows: 0
+
+ {% for prog, item in programs.items() if item.type == 'lib' %}
+ * - .. image:: {{img_path}}/{{item.icon}}
+ :target: {{intersphinx_mapping['%s' | format(prog)][0]}}
+ :class: labscript-suite-icon
+ - |{{prog}}|_ --- {{item.desc}}
+ {% endfor %}
+
+.. list-table:: Graphical applications
+ :widths: 10 90
+ :header-rows: 0
+
+ {% for prog, item in programs.items() if item.type == 'gui' %}
+ * - .. image:: {{img_path}}/{{item.icon}}
+ :target: {{intersphinx_mapping['%s' | format(prog)][0]}}
+ :class: labscript-suite-icon
+ - |{{prog}}|_ --- {{item.desc}}
+ {% endfor %}
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+
+ {% for prog in programs|sort if prog != current_project %}
+ {{prog}} <{{intersphinx_mapping['%s' | format(prog)][0]}}>
+ {% endfor %}
+
+{% for prog in programs %}
+.. |{{prog}}| replace:: **{{prog}}**
+.. _{{prog}}: {{intersphinx_mapping['%s' | format(prog)][0]}}
+{% endfor %}
\ No newline at end of file
diff --git a/docs/source/api_reference/connections.rst b/docs/source/api/connections.rst
similarity index 100%
rename from docs/source/api_reference/connections.rst
rename to docs/source/api/connections.rst
diff --git a/docs/source/api_reference/index.rst b/docs/source/api/index.rst
similarity index 100%
rename from docs/source/api_reference/index.rst
rename to docs/source/api/index.rst
diff --git a/docs/source/api_reference/labscript_utils.rst b/docs/source/api/labscript_utils.rst
similarity index 100%
rename from docs/source/api_reference/labscript_utils.rst
rename to docs/source/api/labscript_utils.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
index a458123..675d806 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -11,8 +11,10 @@
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
+from pathlib import Path
from m2r import MdInclude
from recommonmark.transform import AutoStructify
+from jinja2 import FileSystemLoader, Environment
# -- Project information (unique to each project) -------------------------------------
@@ -26,8 +28,9 @@
release = version
# HTML icons
-html_logo = "img/{}.svg".format(project)
-html_favicon = "img/{}.ico".format(project)
+img_path = 'img'
+html_logo = img_path + "/labscript_64x64.svg"
+html_favicon = img_path + "/labscript.ico"
# -- General configuration (should be identical across all projects) ------------------
@@ -79,38 +82,66 @@
'matplotlib': ('https://matplotlib.org/', None),
'h5py': ('http://docs.h5py.org/en/stable/', None),
'pydaqmx': ('https://pythonhosted.org/PyDAQmx/', None),
- # from https://github.com/MSLNZ/msl-qt/blob/master/docs/create_pyqt_objects.py
- # under MIT License
'qt': (
'',
'pyqt5-modified-objects.inv',
- )
+ ) # from https://github.com/MSLNZ/msl-qt/blob/master/docs/create_pyqt_objects.py
+ # under MIT License
# TODO
# desktop-app
# spinapi/pynivision/etc
}
# list of all labscript suite components that have docs
-labscript_suite_programs = [
- 'labscript',
- 'runmanager',
- 'runviewer',
- 'blacs',
- 'lyse',
- 'labscript-utils',
- 'labscript-devices',
-]
-# remove this current repo from the list
-if project in labscript_suite_programs:
- labscript_suite_programs.remove(project)
+labscript_suite_programs = {
+ 'labscript': {
+ 'desc': 'Expressive composition of hardware-timed experiments',
+ 'icon': 'labscript_32nx32n.svg',
+ 'type': 'lib',
+ },
+ 'labscript-devices': {
+ 'desc': 'Plugin architecture for controlling experiment hardware',
+ 'icon': 'labscript_32nx32n.svg',
+ 'type': 'lib',
+ },
+ 'labscript-utils': {
+ 'desc': 'Shared modules used by the *labscript suite*',
+ 'icon': 'labscript_32nx32n.svg',
+ 'type': 'lib',
+ },
+ 'runmanager': {
+ 'desc': 'Graphical and remote interface to parameterized experiments',
+ 'icon': 'runmanager_32nx32n.svg',
+ 'type': 'gui',
+ },
+ 'blacs': {
+ 'desc': 'Graphical interface to scientific instruments and experiment supervision',
+ 'icon': 'blacs_32nx32n.svg',
+ 'type': 'gui',
+ },
+ 'lyse': {
+ 'desc': 'Online analysis of live experiment data',
+ 'icon': 'lyse_32nx32n.svg',
+ 'type': 'gui',
+ },
+ 'runviewer': {
+ 'desc': 'Visualize hardware-timed experiment instructions',
+ 'icon': 'runviewer_32nx32n.svg',
+ 'type': 'gui',
+ },
+}
# whether to use stable or latest version
-labscript_suite_doc_version = 'stable' # 'stable' or 'latest'
+labscript_suite_doc_version = os.environ.get('READTHEDOCS_VERSION', 'latest')
+if '.' in labscript_suite_doc_version:
+ labscript_suite_doc_version = 'stable'
+elif labscript_suite_doc_version not in ['stable', 'latest']:
+ labscript_suite_doc_version = 'latest'
# add intersphinx references for each component
for ls_prog in labscript_suite_programs:
intersphinx_mapping[ls_prog] = (
- 'https://docs.labscript_suite.org/projects/{}/en/{}/'.format(
+ 'https://docs.labscriptsuite.org/projects/{}/en/{}/'.format(
ls_prog, labscript_suite_doc_version
),
None,
@@ -119,7 +150,7 @@
# add intersphinx reference for the metapackage
if project != "the labscript suite":
intersphinx_mapping['labscript-suite'] = (
- 'https://docs.labscript_suite.org/en/{}/'.format(labscript_suite_doc_version),
+ 'https://docs.labscriptsuite.org/en/{}/'.format(labscript_suite_doc_version),
None,
)
@@ -137,6 +168,7 @@
todo_include_todos = False
else:
todo_include_todos = True
+
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -158,7 +190,6 @@
# Customize the html_theme
html_theme_options = {'navigation_depth': 3}
-
# Use m2r only for mdinclude and recommonmark for everything else
# https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992
def setup(app):
@@ -176,4 +207,19 @@ def setup(app):
app.add_config_value('m2r_anonymous_references', False, 'env')
app.add_config_value('m2r_disable_inline_math', False, 'env')
app.add_directive('mdinclude', MdInclude)
- app.add_stylesheet('custom.css')
+ app.add_css_file('custom.css')
+
+ # generate the components.rst file dynamically so it points to stable/latest
+ # of subprojects correctly
+ loader = FileSystemLoader(Path(__file__).resolve().parent / templates_path[0])
+ env = Environment(loader=loader)
+ template = env.get_template('components.rst')
+ with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f:
+ f.write(
+ template.render(
+ intersphinx_mapping=intersphinx_mapping,
+ programs=labscript_suite_programs,
+ current_project=project,
+ img_path=img_path
+ )
+ )
diff --git a/docs/source/img/blacs_32nx32n.svg b/docs/source/img/blacs_32nx32n.svg
new file mode 100644
index 0000000..d6a2b0e
--- /dev/null
+++ b/docs/source/img/blacs_32nx32n.svg
@@ -0,0 +1,178 @@
+
+
diff --git a/docs/source/img/labscript-suite-rectangular-transparent_138nx70n.svg b/docs/source/img/labscript-suite-rectangular-transparent_138nx70n.svg
new file mode 100644
index 0000000..828b77e
--- /dev/null
+++ b/docs/source/img/labscript-suite-rectangular-transparent_138nx70n.svg
@@ -0,0 +1,579 @@
+
+
diff --git a/docs/source/img/labscript-utils.svg b/docs/source/img/labscript-utils.svg
deleted file mode 100644
index 24d9ee6..0000000
--- a/docs/source/img/labscript-utils.svg
+++ /dev/null
@@ -1,112 +0,0 @@
-
-
diff --git a/docs/source/img/labscript-utils.ico b/docs/source/img/labscript.ico
similarity index 100%
rename from docs/source/img/labscript-utils.ico
rename to docs/source/img/labscript.ico
diff --git a/docs/source/img/labscript_32nx32n.svg b/docs/source/img/labscript_32nx32n.svg
new file mode 100644
index 0000000..97272af
--- /dev/null
+++ b/docs/source/img/labscript_32nx32n.svg
@@ -0,0 +1,186 @@
+
+
diff --git a/docs/source/img/labscript_64x64.svg b/docs/source/img/labscript_64x64.svg
new file mode 100644
index 0000000..987cfe6
--- /dev/null
+++ b/docs/source/img/labscript_64x64.svg
@@ -0,0 +1,42 @@
+
+
diff --git a/docs/source/img/lyse_32nx32n.svg b/docs/source/img/lyse_32nx32n.svg
new file mode 100644
index 0000000..1ddcdcc
--- /dev/null
+++ b/docs/source/img/lyse_32nx32n.svg
@@ -0,0 +1,256 @@
+
+
diff --git a/docs/source/img/runmanager_32nx32n.svg b/docs/source/img/runmanager_32nx32n.svg
new file mode 100644
index 0000000..d9df689
--- /dev/null
+++ b/docs/source/img/runmanager_32nx32n.svg
@@ -0,0 +1,267 @@
+
+
diff --git a/docs/source/img/runviewer_32nx32n.svg b/docs/source/img/runviewer_32nx32n.svg
new file mode 100644
index 0000000..ee5aa68
--- /dev/null
+++ b/docs/source/img/runviewer_32nx32n.svg
@@ -0,0 +1,223 @@
+
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 7956870..86f2cab 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -11,6 +11,27 @@ This documentation is primarily for developers who might want to use this common
.. toctree::
:maxdepth: 2
+ :hidden:
+ :caption: DOCUMENTATION
- api_reference/index
+ api/index
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+ :caption: FURTHER DOCUMENTATION
+
+ components
+
+.. toctree::
+ :maxdepth: 2
+ :hidden:
+ :caption: LINKS
+
+ Home Page Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies: