Merge pull request #56 from philipstarkey/master

Added links to other component docs

Author: philipstarkey

.gitignore

@@ -1,3 +1,10 @@
+# This gitignore file consists of 2 parts:
+#   * The standard Python .gitignore rules from GitHub
+#   * custom ignore rules for the labscript suite.
+#
+# These should be kept separate so that the generic rules can be updated with a
+# copy/paste without having to worry about whether we are removing custom rules
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -20,7 +27,6 @@ parts/
 sdist/
 var/
 wheels/
-pip-wheel-metadata/
 share/python-wheels/
 *.egg-info/
 .installed.cfg
@@ -50,6 +56,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+cover/
 
 # Translations
 *.mo
@@ -69,11 +76,10 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/html/
 docs/_build/
-docs/source/_build/
 
 # PyBuilder
+.pybuilder/
 target/
 
 # Jupyter Notebook
@@ -84,6 +90,8 @@ profile_default/
 ipython_config.py
 
 # pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
 .python-version
 
 # pipenv
@@ -130,9 +138,24 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+#
+# Custom labscript suite .gitignore rules start below
+#
+
 # Editors
 .vscode/
 
 # conda build results
 conda_build/
 conda_packages/
+
+# Sphinx documentation
+docs/html/
+docs/source/_build/
+docs/source/components.rst

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;
+}

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 %}

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,64 @@
     '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 labscript_suite_doc_version not in ['stable', 'latest']:
+    labscript_suite_doc_version = 'stable'
 
 # 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 +148,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 +166,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 +188,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):
@@ -177,3 +206,18 @@ def setup(app):
     app.add_config_value('m2r_disable_inline_math', False, 'env')
     app.add_directive('mdinclude', MdInclude)
     app.add_stylesheet('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
+            )
+        )