diff --git a/.gitignore b/.gitignore index 247f33c..adca393 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,138 @@ -__pycache__ -dist -*.egg-info -*eggs -conda_build -conda_packages -build/* \ No newline at end of file +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/html/ +docs/_build/ +docs/source/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# Editors +.vscode/ + +# conda build results +conda_build/ +conda_packages/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..9534b01 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..ad5c1a8 --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,59 @@ +/* Add space between collapsible details HTML tags */ +details { + margin-bottom: 1em; +} + +/* Darker pygment highlighing of console input/output */ +.highlight .go { + color: #404040; +} + +/* White captions in sidebar */ +.wy-nav-side p.caption { + color: #f5f5f5; +} + +/* labscript blue, alpha = 83% */ +.wy-side-nav-search { + background: #2946bbd3; +} + +.wy-nav-top { + background: #2946bbd3; +} + +/* labscript green, alpha = 75% */ +.rst-content .note .admonition-title { + background: #00804fbf; +} + +/* labscript green, alpha = 25% */ +.rst-content .note { + background: #00804f3f; +} + +/* labscript red, alpha = 75% */ +.rst-content .warning .admonition-title { + background: #bc294cbf +} + +/* labscript red, alpha = 25% */ +.rst-content .warning { + background: #bc294c3b; +} + +/* Elevation +* +* Style box-shadows using Material Design's idea of elevation. These particular numbers are taken from here: +* +* https://github.com/material-components/material-components-web +* https://material-components-web.appspot.com/elevation.html +*/ + +.rst-content img.screenshot { + border: none; + /* MD Elevation 8 */ + box-shadow: 0px 5px 5px -3px rgba(0, 0, 0, 0.2), + 0px 8px 10px 1px rgba(0, 0, 0, 0.14), 0px 3px 14px 2px rgba(0, 0, 0, 0.12); + margin-bottom: 24px; +} diff --git a/docs/source/api_reference/connections.rst b/docs/source/api_reference/connections.rst new file mode 100644 index 0000000..1dbdaf3 --- /dev/null +++ b/docs/source/api_reference/connections.rst @@ -0,0 +1,7 @@ +=========================== +labscript_utils.connections +=========================== + +.. automodule:: labscript_utils.connections + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/source/api_reference/index.rst b/docs/source/api_reference/index.rst new file mode 100644 index 0000000..bfaf552 --- /dev/null +++ b/docs/source/api_reference/index.rst @@ -0,0 +1,9 @@ +************* +API Reference +************* + +.. toctree:: + :maxdepth: 2 + + labscript_utils + connections \ No newline at end of file diff --git a/docs/source/api_reference/labscript_utils.rst b/docs/source/api_reference/labscript_utils.rst new file mode 100644 index 0000000..f73d1e1 --- /dev/null +++ b/docs/source/api_reference/labscript_utils.rst @@ -0,0 +1,7 @@ +=============== +labscript_utils +=============== + +.. automodule:: labscript_utils + :members: + :undoc-members: \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..a458123 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,179 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +from m2r import MdInclude +from recommonmark.transform import AutoStructify + +# -- Project information (unique to each project) ------------------------------------- + +project = "labscript-utils" +copyright = "2020, labscript suite" +author = "labscript suite contributors" + +# The full version, including alpha/beta/rc tags +from labscript_utils import __version__ as version # noqa: E402 + +release = version + +# HTML icons +html_logo = "img/{}.svg".format(project) +html_favicon = "img/{}.ico".format(project) + +# -- General configuration (should be identical across all projects) ------------------ + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx.ext.intersphinx", + "sphinx.ext.napoleon", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx_rtd_theme", + "recommonmark", +] + +autodoc_typehints = 'description' + +# Prefix each autosectionlabel with the name of the document it is in and a colon +autosectionlabel_prefix_document = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The suffix(es) of source filenames. +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# intersphinx allows us to link directly to other repos sphinxdocs. +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'numpy': ('https://numpy.org/doc/stable/', None), + 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), + 'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None), + 'qtutils': ('https://qtutils.readthedocs.io/en/stable/', None), + 'pyqtgraph': ( + 'https://pyqtgraph.readthedocs.io/en/latest/', + None, + ), # change to stable once v0.11 is published + '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', + ) + # 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) + +# whether to use stable or latest version +labscript_suite_doc_version = 'stable' # 'stable' or '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( + ls_prog, labscript_suite_doc_version + ), + None, + ) + +# 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), + None, + ) + +# Make `some code` equivalent to :code:`some code` +default_role = 'code' + +# hide todo notes if on readthedocs and not building the latest +if os.environ.get('READTHEDOCS') and ( + os.environ.get('READTHEDOCS_VERSION') != 'latest' + or ( + os.environ.get('READTHEDOCS_PROJECT') == project + or os.environ.get('READTHEDOCS_PROJECT') == 'labscriptsuite' + ) +): + 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 +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" +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, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# 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): + config = { + # 'url_resolver': lambda url: github_doc_root + url, + 'auto_toc_tree_section': 'Contents', + 'enable_eval_rst': True, + } + app.add_config_value('recommonmark_config', config, True) + app.add_transform(AutoStructify) + + # from m2r to make `mdinclude` work + app.add_config_value('no_underscore_emphasis', False, 'env') + app.add_config_value('m2r_parse_relative_links', False, 'env') + 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') diff --git a/docs/source/img/labscript-utils.ico b/docs/source/img/labscript-utils.ico new file mode 100644 index 0000000..28288fc Binary files /dev/null and b/docs/source/img/labscript-utils.ico differ diff --git a/docs/source/img/labscript-utils.svg b/docs/source/img/labscript-utils.svg new file mode 100644 index 0000000..24d9ee6 --- /dev/null +++ b/docs/source/img/labscript-utils.svg @@ -0,0 +1,112 @@ + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..7956870 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,16 @@ +.. labscript-utils documentation master file, created by + sphinx-quickstart on Sun May 31 21:24:37 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +labscript-utils +=============== + +**labscript-utils** contains code shared between multiple programs in the labscript suite. +This documentation is primarily for developers who might want to use this common code in their own custom features. + +.. toctree:: + :maxdepth: 2 + + api_reference/index + diff --git a/docs/source/pyqt5-modified-objects.inv b/docs/source/pyqt5-modified-objects.inv new file mode 100644 index 0000000..418cb89 Binary files /dev/null and b/docs/source/pyqt5-modified-objects.inv differ diff --git a/readthedocs.yaml b/readthedocs.yaml new file mode 100644 index 0000000..35084d6 --- /dev/null +++ b/readthedocs.yaml @@ -0,0 +1,27 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: dirhtml + configuration: docs/source/conf.py + fail_on_warning: false + +# Optionally build your docs in additional formats such as PDF +formats: + - pdf + - epub + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - method: pip + path: . + extra_requirements: + - docs + system_packages: true + \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index fb59d3a..a7433e0 100644 --- a/setup.cfg +++ b/setup.cfg @@ -34,6 +34,14 @@ install_requires = setuptools_scm zprocess>=2.18.0 +[options.extras_require] +docs = + PyQt5 + Sphinx==3.0.1 + sphinx-rtd-theme==0.4.3 + recommonmark==0.6.0 + m2r==0.2.1 + [options.package_data] labscript_profile = ../labscript-suite.pth