From 0f0da2edfd924c11226f1211296840dd23fa13bb Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Tue, 16 Jun 2020 18:06:02 +1000 Subject: [PATCH 01/12] Added links to other component docs --- .gitignore | 5 ++++- docs/source/conf.py | 28 +++++++++++++++++++++++++--- docs/source/index.rst | 3 ++- 3 files changed, 31 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index e1176b2..093f374 100644 --- a/.gitignore +++ b/.gitignore @@ -129,4 +129,7 @@ dmypy.json .pyre/ # Editors -.vscode/ \ No newline at end of file +.vscode/ + +# dynamically generated docs +docs/source/component_docs.rst \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 665ab67..b806e32 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -105,7 +105,9 @@ labscript_suite_programs.remove(project) # 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: @@ -143,9 +145,10 @@ # 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, @@ -175,3 +178,22 @@ def setup(app): app.add_config_value('m2r_disable_inline_math', False, 'env') app.add_directive('mdinclude', MdInclude) app.add_stylesheet('custom.css') + + with open( + os.path.join(os.path.dirname(os.path.realpath(__file__)), 'component_docs.rst'), + 'w', + ) as f: + f.write("labscript suite components\n") + f.write("==========================\n") + f.write(" \n") + f.write(".. toctree::\n") + f.write(" :maxdepth: 2\n") + f.write(" \n") + if project != "the labscript suite": + f.write( + " labscript suite (metapackage)<{}>\n".format( + intersphinx_mapping['labscript-suite'][0] + ) + ) + for ls_prog in labscript_suite_programs: + f.write(" {} <{}>\n".format(ls_prog, intersphinx_mapping[ls_prog][0])) diff --git a/docs/source/index.rst b/docs/source/index.rst index 735378e..ebf76a5 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -71,8 +71,9 @@ installation/index changes contributing - archive + component_docs Home Page Source Code + archive .. todolist:: From 8e5ea93cf0be3849161a0f6c8d382aa269c7b999 Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Tue, 16 Jun 2020 18:08:33 +1000 Subject: [PATCH 02/12] black formatting --- docs/source/conf.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b806e32..b9309a5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -147,7 +147,9 @@ # html_theme = "sphinx_rtd_theme" html_title = "labscript suite | {project}".format( - project=project if project != "labscript-suite" else "experiment control and automation" + project=project + if project != "labscript-suite" + else "experiment control and automation" ) html_short_title = "labscript suite" From b3087a627abad9796f2d677251e30c30eec06bb8 Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 11:10:54 +1000 Subject: [PATCH 03/12] Implemented some review changes * fixed typo in labscriptsuite.org URLs * Updated to use `pathlib` * Updated .gitignore to delineate custom and generic ignore rules * renamed component_docs.rst -> components.rst --- .gitignore | 21 ++++++++++++++------- docs/source/conf.py | 14 ++++++-------- docs/source/index.rst | 2 +- 3 files changed, 21 insertions(+), 16 deletions(-) diff --git a/.gitignore b/.gitignore index 093f374..9f06bbf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,16 @@ +# Editors +.vscode/ + +# dynamically generated docs +docs/source/components.rst + +# +# The above is custom entries for the labscript suite project +# +# The below is the standard GitHub Python .gitignore list. This contains no custom +# entries and can be updated with copy/paste in the future +# + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] @@ -126,10 +139,4 @@ venv.bak/ dmypy.json # Pyre type checker -.pyre/ - -# Editors -.vscode/ - -# dynamically generated docs -docs/source/component_docs.rst \ No newline at end of file +.pyre/ \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index b9309a5..06d69e2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,6 +11,7 @@ # 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 @@ -112,7 +113,7 @@ # 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, @@ -121,7 +122,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, ) @@ -181,12 +182,9 @@ def setup(app): app.add_directive('mdinclude', MdInclude) app.add_stylesheet('custom.css') - with open( - os.path.join(os.path.dirname(os.path.realpath(__file__)), 'component_docs.rst'), - 'w', - ) as f: - f.write("labscript suite components\n") - f.write("==========================\n") + with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f: + f.write("*labscript suite* components\n") + f.write("============================\n") f.write(" \n") f.write(".. toctree::\n") f.write(" :maxdepth: 2\n") diff --git a/docs/source/index.rst b/docs/source/index.rst index ebf76a5..c14fcac 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -71,7 +71,7 @@ installation/index changes contributing - component_docs + components Home Page Source Code archive From 58ed4fdee0ca74b7e67c3b181d27848516c69675 Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 12:31:24 +1000 Subject: [PATCH 04/12] Added dynamic generation of labscript suite component table --- docs/source/_static/custom.css | 4 ++ docs/source/conf.py | 126 ++++++++++++++++++++++++++------- 2 files changed, 105 insertions(+), 25 deletions(-) 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/conf.py b/docs/source/conf.py index 06d69e2..c4014d3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -28,8 +28,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) ------------------ @@ -92,15 +93,43 @@ } # list of all labscript suite components that have docs -labscript_suite_programs = [ - 'labscript', - 'runmanager', - 'runviewer', - 'blacs', - 'lyse', - 'labscript-utils', - 'labscript-devices', -] +labscript_suite_programs = { + 'labscript': { + 'desc': 'Expressive composition of hardware-timed experiments', + 'img': img_path+'/labscript_32nx32n.svg', + 'type': 'lib', + }, + 'labscript-devices': { + 'desc': 'Plugin architecture for controlling experiment hardware', + 'img': img_path+'/labscript_32nx32n.svg', + 'type': 'lib', + }, + 'labscript-utils': { + 'desc': 'Shared modules used by the *labscript suite*', + 'img': img_path+'/labscript_32nx32n.svg', + 'type': 'lib', + }, + 'runmanager': { + 'desc': 'Graphical and remote interface to parameterized experiments', + 'img': img_path+'/runmanager_32nx32n.svg', + 'type': 'gui', + }, + 'blacs': { + 'desc': 'Graphical interface to scientific instruments and experiment supervision', + 'img': img_path+'/blacs_32nx32n.svg', + 'type': 'gui', + }, + 'lyse': { + 'desc': 'Online analysis of live experiment data', + 'img': img_path+'/lyse_32nx32n.svg', + 'type': 'gui', + }, + 'runviewer': { + 'desc': 'Visualize hardware-timed experiment instructions', + 'img': img_path+'/runviewer_32nx32n.svg', + 'type': 'gui', + }, +} # remove this current repo from the list if project in labscript_suite_programs: labscript_suite_programs.remove(project) @@ -162,6 +191,48 @@ # Customize the html_theme html_theme_options = {'navigation_depth': 3} +# Template for generating the components.rst file +# fmt:off +components_rst_template = \ +"""*labscript suite* components +============================ + +The *labscript suite* is modular by design, and is comprised of: + +.. list-table:: Python libraries + :widths: 10 90 + :header-rows: 0 + +{lib} + +.. list-table:: Graphical applications + :widths: 10 90 + :header-rows: 0 + +{gui} + +.. toctree:: + :maxdepth: 2 + :hidden: + +{toctree_entires} + + +{rst_defs} +""" + +components_rst_table_template = \ +""" * - .. image:: {img} + :target: https://docs.labscriptsuite.org/projects/{prog}/en/latest/ + :class: labscript-suite-icon + - |{prog}|_ --- {desc} +""" + +components_rst_link_template = \ +""".. |{prog}| replace:: **{prog}** +.. _{prog}: https://docs.labscriptsuite.org/projects/{prog}/en/latest/ +""" +# fmt:on # Use m2r only for mdinclude and recommonmark for everything else # https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992 @@ -182,18 +253,23 @@ def setup(app): 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 + components_rst_table = { + "lib": "", + "gui": "", + } + components_rst_link = "" + components_rst_toctree = "" + for ls_prog, data in labscript_suite_programs.items(): + components_rst_table[data['type']] += components_rst_table_template.format( + prog=ls_prog, **data + ) + components_rst_link += components_rst_link_template.format(prog=ls_prog) + for ls_prog in sorted(labscript_suite_programs): + components_rst_toctree += " {} <{}>\n".format(ls_prog, intersphinx_mapping[ls_prog][0]) + + components_rst = components_rst_template.format(toctree_entires=components_rst_toctree, rst_defs=components_rst_link, **components_rst_table) + with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f: - f.write("*labscript suite* components\n") - f.write("============================\n") - f.write(" \n") - f.write(".. toctree::\n") - f.write(" :maxdepth: 2\n") - f.write(" \n") - if project != "the labscript suite": - f.write( - " labscript suite (metapackage)<{}>\n".format( - intersphinx_mapping['labscript-suite'][0] - ) - ) - for ls_prog in labscript_suite_programs: - f.write(" {} <{}>\n".format(ls_prog, intersphinx_mapping[ls_prog][0])) + f.write(components_rst) From a00526b2e54f79d388aa8e4adcd8dd9062d33f2a Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 13:06:16 +1000 Subject: [PATCH 05/12] Fixed bug where component docs URLs were alsways using "latest". * Now use the intersphinx mapping URL already generated * Also added entry for metapackage --- docs/source/conf.py | 63 +++++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c4014d3..e73a587 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -29,8 +29,8 @@ # HTML icons img_path = "../../art" -html_logo = img_path+"/labscript-suite-rectangular-transparent_276x140.svg" -html_favicon = img_path+"/labscript.ico" +html_logo = img_path + "/labscript-suite-rectangular-transparent_276x140.svg" +html_favicon = img_path + "/labscript.ico" # -- General configuration (should be identical across all projects) ------------------ @@ -96,37 +96,37 @@ labscript_suite_programs = { 'labscript': { 'desc': 'Expressive composition of hardware-timed experiments', - 'img': img_path+'/labscript_32nx32n.svg', + 'img': img_path + '/labscript_32nx32n.svg', 'type': 'lib', }, 'labscript-devices': { 'desc': 'Plugin architecture for controlling experiment hardware', - 'img': img_path+'/labscript_32nx32n.svg', + 'img': img_path + '/labscript_32nx32n.svg', 'type': 'lib', }, 'labscript-utils': { 'desc': 'Shared modules used by the *labscript suite*', - 'img': img_path+'/labscript_32nx32n.svg', + 'img': img_path + '/labscript_32nx32n.svg', 'type': 'lib', }, 'runmanager': { 'desc': 'Graphical and remote interface to parameterized experiments', - 'img': img_path+'/runmanager_32nx32n.svg', + 'img': img_path + '/runmanager_32nx32n.svg', 'type': 'gui', }, 'blacs': { 'desc': 'Graphical interface to scientific instruments and experiment supervision', - 'img': img_path+'/blacs_32nx32n.svg', + 'img': img_path + '/blacs_32nx32n.svg', 'type': 'gui', }, 'lyse': { 'desc': 'Online analysis of live experiment data', - 'img': img_path+'/lyse_32nx32n.svg', + 'img': img_path + '/lyse_32nx32n.svg', 'type': 'gui', }, 'runviewer': { 'desc': 'Visualize hardware-timed experiment instructions', - 'img': img_path+'/runviewer_32nx32n.svg', + 'img': img_path + '/runviewer_32nx32n.svg', 'type': 'gui', }, } @@ -199,6 +199,15 @@ The *labscript suite* is modular by design, and is comprised of: +.. list-table:: Metapackage + :widths: 10 90 + :header-rows: 0 + + * - .. image:: {metapackage_img} + :target: https://docs.labscriptsuite.org/en/{labscript_suite_doc_version}/ + :class: labscript-suite-icon + - |labscriptsuite|_ --- The metapackage for the *labscript suite* + .. list-table:: Python libraries :widths: 10 90 :header-rows: 0 @@ -218,19 +227,21 @@ {toctree_entires} +.. |labscriptsuite| replace:: **labscriptsuite** +.. _labscriptsuite: https://docs.labscriptsuite.org/en/{labscript_suite_doc_version}/ {rst_defs} """ components_rst_table_template = \ """ * - .. image:: {img} - :target: https://docs.labscriptsuite.org/projects/{prog}/en/latest/ + :target: {target} :class: labscript-suite-icon - |{prog}|_ --- {desc} """ components_rst_link_template = \ """.. |{prog}| replace:: **{prog}** -.. _{prog}: https://docs.labscriptsuite.org/projects/{prog}/en/latest/ +.. _{prog}: {target} """ # fmt:on @@ -261,15 +272,35 @@ def setup(app): } components_rst_link = "" components_rst_toctree = "" + if project != 'the labscript suite': + components_rst_toctree += "*labscript suite* metapackage <{}>\n".format( + intersphinx_mapping['labscript-suite'][0] + ) + metapackage_img = img_path + "/labscript-suite-rectangular-transparent_138nx70n.svg" for ls_prog, data in labscript_suite_programs.items(): components_rst_table[data['type']] += components_rst_table_template.format( - prog=ls_prog, **data + prog=ls_prog, + labscript_suite_doc_version=labscript_suite_doc_version, + target=intersphinx_mapping[ls_prog][0], + **data + ) + components_rst_link += components_rst_link_template.format( + prog=ls_prog, + labscript_suite_doc_version=labscript_suite_doc_version, + target=intersphinx_mapping[ls_prog][0], ) - components_rst_link += components_rst_link_template.format(prog=ls_prog) for ls_prog in sorted(labscript_suite_programs): - components_rst_toctree += " {} <{}>\n".format(ls_prog, intersphinx_mapping[ls_prog][0]) - - components_rst = components_rst_template.format(toctree_entires=components_rst_toctree, rst_defs=components_rst_link, **components_rst_table) + components_rst_toctree += " {} <{}>\n".format( + ls_prog, intersphinx_mapping[ls_prog][0] + ) + + components_rst = components_rst_template.format( + toctree_entires=components_rst_toctree, + rst_defs=components_rst_link, + metapackage_img=metapackage_img, + labscript_suite_doc_version=labscript_suite_doc_version, + **components_rst_table + ) with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f: f.write(components_rst) From cb399ecde7c9161c2ff5c1e74744a6f0bfd27b59 Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 16:09:49 +1000 Subject: [PATCH 06/12] Split out metapackage link in generalised config (hidden in docs built for this project) * also removed metapackage table from components page (since I realised I shouldn't have really added it) --- docs/source/conf.py | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index e73a587..3094580 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -130,9 +130,6 @@ 'type': 'gui', }, } -# remove this current repo from the list -if project in labscript_suite_programs: - labscript_suite_programs.remove(project) # whether to use stable or latest version labscript_suite_doc_version = os.environ.get('READTHEDOCS_VERSION', 'latest') @@ -194,20 +191,14 @@ # Template for generating the components.rst file # fmt:off components_rst_template = \ -"""*labscript suite* components +""" +{metapackage_toctree} + +*labscript suite* components ============================ The *labscript suite* is modular by design, and is comprised of: -.. list-table:: Metapackage - :widths: 10 90 - :header-rows: 0 - - * - .. image:: {metapackage_img} - :target: https://docs.labscriptsuite.org/en/{labscript_suite_doc_version}/ - :class: labscript-suite-icon - - |labscriptsuite|_ --- The metapackage for the *labscript suite* - .. list-table:: Python libraries :widths: 10 90 :header-rows: 0 @@ -226,9 +217,6 @@ {toctree_entires} - -.. |labscriptsuite| replace:: **labscriptsuite** -.. _labscriptsuite: https://docs.labscriptsuite.org/en/{labscript_suite_doc_version}/ {rst_defs} """ @@ -243,6 +231,14 @@ """.. |{prog}| replace:: **{prog}** .. _{prog}: {target} """ + +components_rst_metapackage_template = \ +""".. toctree:: + :maxdepth: 2 + :hidden: + + Metapackage documentation <{}> +""" # fmt:on # Use m2r only for mdinclude and recommonmark for everything else @@ -272,8 +268,9 @@ def setup(app): } components_rst_link = "" components_rst_toctree = "" + components_rst_metapackage = "" if project != 'the labscript suite': - components_rst_toctree += "*labscript suite* metapackage <{}>\n".format( + components_rst_metapackage = components_rst_metapackage_template.format( intersphinx_mapping['labscript-suite'][0] ) metapackage_img = img_path + "/labscript-suite-rectangular-transparent_138nx70n.svg" @@ -290,15 +287,16 @@ def setup(app): target=intersphinx_mapping[ls_prog][0], ) for ls_prog in sorted(labscript_suite_programs): - components_rst_toctree += " {} <{}>\n".format( - ls_prog, intersphinx_mapping[ls_prog][0] - ) + if ls_prog != project: + components_rst_toctree += " {} <{}>\n".format( + ls_prog, intersphinx_mapping[ls_prog][0] + ) components_rst = components_rst_template.format( toctree_entires=components_rst_toctree, rst_defs=components_rst_link, - metapackage_img=metapackage_img, labscript_suite_doc_version=labscript_suite_doc_version, + metapackage_toctree=components_rst_metapackage, **components_rst_table ) From 42172f57abc17ef3ca63a603eea674e6dc24bd5f Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 16:32:45 +1000 Subject: [PATCH 07/12] reversed order of sections in .gitignore This is so that custom rules added by git tools will be in the right section when they are appended to the file --- .gitignore | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/.gitignore b/.gitignore index 9f06bbf..4bf2cd2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,15 +1,9 @@ -# Editors -.vscode/ - -# dynamically generated docs -docs/source/components.rst - -# -# The above is custom entries for the labscript suite project -# -# The below is the standard GitHub Python .gitignore list. This contains no custom -# entries and can be updated with copy/paste in the future +# 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__/ @@ -139,4 +133,14 @@ venv.bak/ dmypy.json # Pyre type checker -.pyre/ \ No newline at end of file +.pyre/ + +# +# Custom labscript suite .gitignore rules start below +# + +# Editors +.vscode/ + +# dynamically generated docs +docs/source/components.rst \ No newline at end of file From d697cb9b42b75fa88867bc8093192f8c9baa1b7f Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 16:40:30 +1000 Subject: [PATCH 08/12] Relocated custom sphinx gitignore rules (and restored the original) --- .gitignore | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 4bf2cd2..a185f59 100644 --- a/.gitignore +++ b/.gitignore @@ -76,7 +76,7 @@ instance/ .scrapy # Sphinx documentation -docs/html/ +docs/_build/ # PyBuilder target/ @@ -142,5 +142,7 @@ dmypy.json # Editors .vscode/ -# dynamically generated docs +# Sphinx documentation +docs/html/ +docs/source/_build/ docs/source/components.rst \ No newline at end of file From 81591290bac1d452549d607963c58da5672ff544 Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 16:43:21 +1000 Subject: [PATCH 09/12] Updated .gitignore with latest GitHub defaults --- .gitignore | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index a185f59..622478e 100644 --- a/.gitignore +++ b/.gitignore @@ -27,7 +27,6 @@ parts/ sdist/ var/ wheels/ -pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg @@ -57,6 +56,7 @@ coverage.xml *.py,cover .hypothesis/ .pytest_cache/ +cover/ # Translations *.mo @@ -79,6 +79,7 @@ instance/ docs/_build/ # PyBuilder +.pybuilder/ target/ # Jupyter Notebook @@ -89,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 @@ -135,6 +138,12 @@ dmypy.json # Pyre type checker .pyre/ +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + # # Custom labscript suite .gitignore rules start below # From 6abe116d7e12dda7e427b682a0e171f30decf08c Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Thu, 18 Jun 2020 19:14:25 +1000 Subject: [PATCH 10/12] Moved auto generated components.rst to a jinja2 template --- docs/source/_templates/components.rst | 47 +++++++++++ docs/source/conf.py | 117 ++++++-------------------- docs/source/index.rst | 6 ++ 3 files changed, 79 insertions(+), 91 deletions(-) create mode 100644 docs/source/_templates/components.rst diff --git a/docs/source/_templates/components.rst b/docs/source/_templates/components.rst new file mode 100644 index 0000000..0934223 --- /dev/null +++ b/docs/source/_templates/components.rst @@ -0,0 +1,47 @@ +{% if metapackage_toctree %} +.. toctree:: + :maxdepth: 2 + :hidden: + + Metapackage documentation <{{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 libs.items() %} + * - .. image:: {{item.img}} + :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 guis.items() %} + * - .. image:: {{item.img}} + :target: {{intersphinx_mapping['%s' | format(prog)][0]}} + :class: labscript-suite-icon + - |{{prog}}|_ --- {{item.desc}} + {% endfor %} + +.. toctree:: + :maxdepth: 2 + :hidden: + + {% for prog in toctree_entries %} + {{prog}} <{{intersphinx_mapping['%s' | format(prog)][0]}}> + {% endfor %} + +{% for prog in rst_defs %} +.. |{{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 3094580..4aaadb9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,6 +15,7 @@ import sys from m2r import MdInclude from recommonmark.transform import AutoStructify +from jinja2 import FileSystemLoader, Environment # -- Project information (unique to each project) ------------------------------------- @@ -188,59 +189,6 @@ # Customize the html_theme html_theme_options = {'navigation_depth': 3} -# Template for generating the components.rst file -# fmt:off -components_rst_template = \ -""" -{metapackage_toctree} - -*labscript suite* components -============================ - -The *labscript suite* is modular by design, and is comprised of: - -.. list-table:: Python libraries - :widths: 10 90 - :header-rows: 0 - -{lib} - -.. list-table:: Graphical applications - :widths: 10 90 - :header-rows: 0 - -{gui} - -.. toctree:: - :maxdepth: 2 - :hidden: - -{toctree_entires} - -{rst_defs} -""" - -components_rst_table_template = \ -""" * - .. image:: {img} - :target: {target} - :class: labscript-suite-icon - - |{prog}|_ --- {desc} -""" - -components_rst_link_template = \ -""".. |{prog}| replace:: **{prog}** -.. _{prog}: {target} -""" - -components_rst_metapackage_template = \ -""".. toctree:: - :maxdepth: 2 - :hidden: - - Metapackage documentation <{}> -""" -# fmt:on - # Use m2r only for mdinclude and recommonmark for everything else # https://github.com/readthedocs/recommonmark/issues/191#issuecomment-622369992 def setup(app): @@ -262,43 +210,30 @@ def setup(app): # generate the components.rst file dynamically so it points to stable/latest # of subprojects correctly - components_rst_table = { - "lib": "", - "gui": "", - } - components_rst_link = "" - components_rst_toctree = "" - components_rst_metapackage = "" - if project != 'the labscript suite': - components_rst_metapackage = components_rst_metapackage_template.format( - intersphinx_mapping['labscript-suite'][0] - ) - metapackage_img = img_path + "/labscript-suite-rectangular-transparent_138nx70n.svg" - for ls_prog, data in labscript_suite_programs.items(): - components_rst_table[data['type']] += components_rst_table_template.format( - prog=ls_prog, - labscript_suite_doc_version=labscript_suite_doc_version, - target=intersphinx_mapping[ls_prog][0], - **data - ) - components_rst_link += components_rst_link_template.format( - prog=ls_prog, - labscript_suite_doc_version=labscript_suite_doc_version, - target=intersphinx_mapping[ls_prog][0], - ) - for ls_prog in sorted(labscript_suite_programs): - if ls_prog != project: - components_rst_toctree += " {} <{}>\n".format( - ls_prog, intersphinx_mapping[ls_prog][0] + 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( + metapackage_toctree=project != 'the labscript suite', + intersphinx_mapping=intersphinx_mapping, + libs=dict( + filter( + lambda x: x[1]['type'] == 'lib', + labscript_suite_programs.items(), + ) + ), + guis=dict( + filter( + lambda x: x[1]['type'] == 'gui', + labscript_suite_programs.items(), + ) + ), + toctree_entries=list( + filter(lambda x: x != project, sorted(labscript_suite_programs)) + ), + rst_defs=labscript_suite_programs, ) + ) - components_rst = components_rst_template.format( - toctree_entires=components_rst_toctree, - rst_defs=components_rst_link, - labscript_suite_doc_version=labscript_suite_doc_version, - metapackage_toctree=components_rst_metapackage, - **components_rst_table - ) - - with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f: - f.write(components_rst) diff --git a/docs/source/index.rst b/docs/source/index.rst index c14fcac..c65a2de 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -71,6 +71,12 @@ installation/index changes contributing + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: LINKS + components Home Page Source Code From d5e175b67efa2d26617d49365d50643f9602b971 Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Fri, 19 Jun 2020 10:56:52 +1000 Subject: [PATCH 11/12] Simplified sphinx conf by moving logic into template --- docs/source/_templates/components.rst | 12 ++++++------ docs/source/conf.py | 20 ++------------------ docs/source/index.rst | 10 ++++++++-- 3 files changed, 16 insertions(+), 26 deletions(-) diff --git a/docs/source/_templates/components.rst b/docs/source/_templates/components.rst index 0934223..c3e5b16 100644 --- a/docs/source/_templates/components.rst +++ b/docs/source/_templates/components.rst @@ -1,9 +1,9 @@ -{% if metapackage_toctree %} +{% if current_project != 'the labscript suite' %} .. toctree:: :maxdepth: 2 :hidden: - Metapackage documentation <{{intersphinx_mapping['labscript-suite'][0]}}> + The labscript suite <{{intersphinx_mapping['labscript-suite'][0]}}> {% endif %} *labscript suite* components @@ -15,7 +15,7 @@ The *labscript suite* is modular by design, and is comprised of: :widths: 10 90 :header-rows: 0 - {% for prog, item in libs.items() %} + {% for prog, item in programs.items() if item.type == 'lib' %} * - .. image:: {{item.img}} :target: {{intersphinx_mapping['%s' | format(prog)][0]}} :class: labscript-suite-icon @@ -26,7 +26,7 @@ The *labscript suite* is modular by design, and is comprised of: :widths: 10 90 :header-rows: 0 - {% for prog, item in guis.items() %} + {% for prog, item in programs.items() if item.type == 'gui' %} * - .. image:: {{item.img}} :target: {{intersphinx_mapping['%s' | format(prog)][0]}} :class: labscript-suite-icon @@ -37,11 +37,11 @@ The *labscript suite* is modular by design, and is comprised of: :maxdepth: 2 :hidden: - {% for prog in toctree_entries %} + {% for prog in programs|sort if prog != current_project %} {{prog}} <{{intersphinx_mapping['%s' | format(prog)][0]}}> {% endfor %} -{% for prog in rst_defs %} +{% 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 4aaadb9..92cd971 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -216,24 +216,8 @@ def setup(app): with open(Path(__file__).resolve().parent / 'components.rst', 'w') as f: f.write( template.render( - metapackage_toctree=project != 'the labscript suite', intersphinx_mapping=intersphinx_mapping, - libs=dict( - filter( - lambda x: x[1]['type'] == 'lib', - labscript_suite_programs.items(), - ) - ), - guis=dict( - filter( - lambda x: x[1]['type'] == 'gui', - labscript_suite_programs.items(), - ) - ), - toctree_entries=list( - filter(lambda x: x != project, sorted(labscript_suite_programs)) - ), - rst_defs=labscript_suite_programs, + programs=labscript_suite_programs, + current_project=project, ) ) - diff --git a/docs/source/index.rst b/docs/source/index.rst index c65a2de..00c3e78 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -75,9 +75,15 @@ .. toctree:: :maxdepth: 2 :hidden: - :caption: LINKS - + :caption: FURTHER DOCUMENTATION + components + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: LINKS + Home Page Source Code archive From 3b8377d0073d034679845f3b325bb2493008ea80 Mon Sep 17 00:00:00 2001 From: philipstarkey Date: Fri, 19 Jun 2020 15:57:44 +1000 Subject: [PATCH 12/12] Addressing latest review comments --- docs/source/_templates/components.rst | 6 +++--- docs/source/conf.py | 15 ++++++++------- docs/source/index.rst | 5 ++++- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/source/_templates/components.rst b/docs/source/_templates/components.rst index c3e5b16..f966939 100644 --- a/docs/source/_templates/components.rst +++ b/docs/source/_templates/components.rst @@ -3,7 +3,7 @@ :maxdepth: 2 :hidden: - The labscript suite <{{intersphinx_mapping['labscript-suite'][0]}}> + the labscript suite <{{intersphinx_mapping['labscript-suite'][0]}}> {% endif %} *labscript suite* components @@ -16,7 +16,7 @@ The *labscript suite* is modular by design, and is comprised of: :header-rows: 0 {% for prog, item in programs.items() if item.type == 'lib' %} - * - .. image:: {{item.img}} + * - .. image:: {{img_path}}/{{item.icon}} :target: {{intersphinx_mapping['%s' | format(prog)][0]}} :class: labscript-suite-icon - |{{prog}}|_ --- {{item.desc}} @@ -27,7 +27,7 @@ The *labscript suite* is modular by design, and is comprised of: :header-rows: 0 {% for prog, item in programs.items() if item.type == 'gui' %} - * - .. image:: {{item.img}} + * - .. image:: {{img_path}}/{{item.icon}} :target: {{intersphinx_mapping['%s' | format(prog)][0]}} :class: labscript-suite-icon - |{{prog}}|_ --- {{item.desc}} diff --git a/docs/source/conf.py b/docs/source/conf.py index 92cd971..0dcc8e6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -97,37 +97,37 @@ labscript_suite_programs = { 'labscript': { 'desc': 'Expressive composition of hardware-timed experiments', - 'img': img_path + '/labscript_32nx32n.svg', + 'icon': 'labscript_32nx32n.svg', 'type': 'lib', }, 'labscript-devices': { 'desc': 'Plugin architecture for controlling experiment hardware', - 'img': img_path + '/labscript_32nx32n.svg', + 'icon': 'labscript_32nx32n.svg', 'type': 'lib', }, 'labscript-utils': { 'desc': 'Shared modules used by the *labscript suite*', - 'img': img_path + '/labscript_32nx32n.svg', + 'icon': 'labscript_32nx32n.svg', 'type': 'lib', }, 'runmanager': { 'desc': 'Graphical and remote interface to parameterized experiments', - 'img': img_path + '/runmanager_32nx32n.svg', + 'icon': 'runmanager_32nx32n.svg', 'type': 'gui', }, 'blacs': { 'desc': 'Graphical interface to scientific instruments and experiment supervision', - 'img': img_path + '/blacs_32nx32n.svg', + 'icon': 'blacs_32nx32n.svg', 'type': 'gui', }, 'lyse': { 'desc': 'Online analysis of live experiment data', - 'img': img_path + '/lyse_32nx32n.svg', + 'icon': 'lyse_32nx32n.svg', 'type': 'gui', }, 'runviewer': { 'desc': 'Visualize hardware-timed experiment instructions', - 'img': img_path + '/runviewer_32nx32n.svg', + 'icon': 'runviewer_32nx32n.svg', 'type': 'gui', }, } @@ -219,5 +219,6 @@ def setup(app): 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 00c3e78..283e3da 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -67,10 +67,12 @@ .. toctree:: :maxdepth: 2 :hidden: + :caption: DOCUMENTATION installation/index changes contributing + archive .. toctree:: :maxdepth: 2 @@ -86,6 +88,7 @@ Home Page Source Code - archive + PyPI + Anaconda Cloud .. todolist::