labscript-suite · philipstarkey · Jun 19, 2020 · Jun 16, 2020 · Jun 16, 2020 · Jun 18, 2020
diff --git a/.gitignore b/.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,9 +76,10 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/html/
+docs/_build/
 
 # PyBuilder
+.pybuilder/
 target/
 
 # Jupyter Notebook
@@ -82,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
@@ -128,5 +138,20 @@ 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/
+.vscode/
+
+# Sphinx documentation
+docs/html/
+docs/source/_build/
+docs/source/components.rst
diff --git 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;
+}
diff --git a/docs/source/_templates/components.rst 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 %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -11,9 +11,11 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+from pathlib import Path
 import sys
 from m2r import MdInclude
 from recommonmark.transform import AutoStructify
+from jinja2 import FileSystemLoader, Environment
 
 # -- Project information (unique to each project) -------------------------------------
 
@@ -27,8 +29,9 @@
 release = version
 
 # HTML icons
-html_logo = "../../art/labscript-suite-rectangular-transparent_276x140.svg"
-html_favicon = "../../art/labscript.ico"
+img_path = "../../art"
+html_logo = img_path + "/labscript-suite-rectangular-transparent_276x140.svg"
+html_favicon = img_path + "/labscript.ico"
 
 # -- General configuration (should be identical across all projects) ------------------
 
@@ -91,26 +94,53 @@
 }
 
 # 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 +149,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,
     )
 
@@ -143,9 +173,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
 html_theme = "sphinx_rtd_theme"
-html_title = "labscript suite | experiment control and automation"
+html_title = "labscript suite | {project}".format(
+    project=project
+    if project != "labscript-suite"
+    else "experiment control and automation"
+)
 html_short_title = "labscript suite"
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -156,7 +189,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):
@@ -175,3 +207,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
+            )
+        )
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -67,12 +67,28 @@
 .. toctree::
    :maxdepth: 2
    :hidden:
+   :caption: DOCUMENTATION
 
    installation/index
    changes
    contributing
    archive
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: FURTHER DOCUMENTATION
+
+   components
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: LINKS
+
    Home Page <http://labscriptsuite.org>
    Source Code <https://github.com/labscript-suite/labscript-suite>
+   PyPI <https://pypi.org/project/labscript-suite/>
+   Anaconda Cloud <https://anaconda.org/labscript-suite/labscript-suite>
 
 .. todolist::