diff --git a/.gitignore b/.gitignore index e1176b2..622478e 100644 --- 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/ \ No newline at end of file +.vscode/ + +# Sphinx documentation +docs/html/ +docs/source/_build/ +docs/source/components.rst \ No newline at end of file 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/conf.py b/docs/source/conf.py index 665ab67..0dcc8e6 100644 --- 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 index 735378e..283e3da 100644 --- 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 Source Code + PyPI + Anaconda Cloud .. todolist::