RTD Documentation

.readthedocs.yaml

@@ -30,4 +30,4 @@ sphinx:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-    - requirements: docs/requirements.txt
+    - requirements: docs/requirements.txt

docs/api.rst

@@ -0,0 +1,12 @@
+API
+===
+..
+   https://stackoverflow.com/questions/2701998/automatically-document-all-modules-recursively-with-sphinx-autodoc
+
+API stuff
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   qnnpy

docs/conf.py

@@ -4,8 +4,13 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+import sys
+
 # -- Path setup --------------------------------------------------------------
 
+sys.path.insert(0, os.path.abspath(os.path.join("..", "src")))
+
 # 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.
@@ -30,7 +35,31 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.napoleon",
+]
+
+autodoc_member_order = "bysource"
+
+napoleon_google_docstring = True
+napoleon_use_param = False
+napoleon_use_rtype = False
+napoleon_include_init_with_doc = False
+napoleon_attr_annotations = True
+
+pygments_style = "sphinx"
+todo_include_todos = True
+
+# https://stackoverflow.com/questions/2701998/automatically-document-all-modules-recursively-with-sphinx-autodoc
+autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -47,13 +76,16 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.10/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
 # -- 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 = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # 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,

docs/dev_install.rst

@@ -0,0 +1,12 @@
+Installation for developers
+===========================
+
+As with the :doc:`user install instructions <user_install>`, ensure that the MariaDB connection C librariees are installed.
+
+In order to allow testing of package code, it is recommended to install the package with ``pip`` as editable:
+
+.. code-block:: bash
+
+    pip install -e /path/to/qnnpy
+
+It is **strongly** recommended to create a separate environment for development work (*e.g.* ``qnnpy-dev``) either using Conda or python venvs.

docs/index.rst

@@ -6,15 +6,20 @@
 Welcome to qnnpy's documentation!
 =================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+``qnnpy`` is a python-based instrument control toolbox for the
+Quantum Nanostructure and Nanofabrication Group (QNN) at MIT.
+The primary goal of this package is to simplify and standardize the measurement of superconducting nanowire single photon detectors (SNSPDs) and other superconducting nanoelectronics.
+This package is split into two main submodules: ``functions``, and ``instruments``.
 
+This reposotory does not contain commands that will perform your measurements for you.
+Its purpose is to organize, standardize, and improve the existing programming infrastructure.
 
+.. note::
+   This project is under active development and the API is subject to change.
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 2
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   api
+   user_install
+   dev_install

docs/requirements.txt

@@ -1,3 +1,8 @@
-ruff
-pre-commit
-matplotlib
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1
+
+numpy
+pyvisa
+scipy
+matplotlib
+nidaqmx

docs/user_install.rst

@@ -0,0 +1,36 @@
+Installation for users
+======================
+
+Ensure the MariaDB connection C libraries are installed and accessible in your environment.
+This is necessary for the ``mariadb`` python library to interface with the database for storage of measurement results (infrastructure for automating this is WIP).
+
+If using a Conda environment (recommended), this can be installed `with <https://anaconda.org/conda-forge/mariadb-connector-c>`_:
+
+.. code-block:: bash
+
+    conda install mariadb-connector-c
+
+If the system already has the connector software installed, then this step isn't necessary
+
+Now ``qnnpy`` can be downloaded and installed with ``pip``:
+
+.. code-block:: bash
+
+    pip install qnnpy
+
+
+PyVISA
+------
+
+``qnnpy`` uses ``pyvisa`` to communicate with a variety of instruments. ``pyvisa`` requires a VISA backend to be installed on the system.
+Most computers in our lab already have a VISA backend installed, but if you're setting up a new system, you will need to install the appropriate libraries.
+
+* `pyvisa-py <https://pyvisa.readthedocs.io/projects/pyvisa-py/en/latest/>`_ implements a VISA backend purely in Python and is very easy to install, but comes with some limitations (*e.g.* connecting multiple GPIB adapters to the same PC).
+
+* `NI-VISA <https://pyvisa.readthedocs.io/en/latest/faq/getting_nivisa.html>`_ is another option, and is what is installed on the lab computers.
+
+USB/GPIB drivers
+----------------
+
+If you are setting up a new system, you will need to make sure that ``pyvisa`` can interface with your instruments.
+Most systems will support TCP/IP devices out of the box, but you may need to install drivers to use the USB or GPIB interfaces on your instruments.

src/qnnpy/__init__.py

@@ -0,0 +1,3 @@
+# ruff: noqa: F401
+
+from . import functions, logging

src/qnnpy/functions/__init__.py

@@ -0,0 +1,18 @@
+# ruff: noqa: F401
+
+from . import (
+    ICE_plot,
+    functions,
+    ic_sweep,
+    laserctrl,
+    laserctrl_cmd_based,
+    logging,
+    microwave,
+    ntron,
+    plotting,
+    resonators,
+    save_data_vs_param,
+    snspd,
+    tc_measurement,
+    tc_measurement_muxed,
+)

src/qnnpy/functions/logging/__init__.py

@@ -0,0 +1,10 @@
+# ruff: noqa: F401
+
+from . import (
+    free_space_cryo_logging,
+    ice_log_pressure_reader,
+    ice_logging,
+    ice_logging_script,
+    janis_300mK_logging,
+    probe_station_logging,
+)

src/qnnpy/instruments/__init__.py

@@ -0,0 +1,58 @@
+# ruff: noqa: F401
+
+from . import (
+    N5224A,
+    AQ4321D_tunable_laser,
+    BK_4060_awg,
+    ThorlabsPM100_meta,
+    __init__,
+    agilent_8153a,
+    agilent_33250a,
+    agilent_33600a,
+    agilent_53131a,
+    agilent_53230a,
+    agilent_e5061b,
+    agilent_n9020a,
+    anritsu_mg9638a,
+    attocube_anc150,
+    attocube_anc300,
+    cryocon34,
+    cryocon350,
+    development_test,
+    exfo_t100s,
+    fva3100_optical_attenuator,
+    hmc_t2240,
+    hp_3478a,
+    hp_8157a,
+    hp_8722c,
+    hp_83711b,
+    jds_ha9,
+    keithley_2001,
+    keithley_2400,
+    keithley_2450,
+    keithley_2700,
+    keithley_6485,
+    keithley_DAQ6510,
+    keysight_53230a,
+    keysight_b2912a,
+    keysight_dsox,
+    keysight_n5224a,
+    keysight_n7752a,
+    labjack_u12,
+    lakeshore336,
+    lecroy_620zi,
+    pollux_motor,
+    redpitaya_12514,
+    rs_sgs100a,
+    santec_tsl,
+    siglent_spd3303,
+    srs_sim928,
+    stanford_sr830,
+    synthhd,
+    tektronix_5014,
+    tektronix_rsa5126a,
+    thorlabs_pm100d,
+    thorlabs_pm101a,
+    yokogawa_aq6370,
+    yokogawa_gs200,
+)