diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 0000000..5661455 --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -0,0 +1,41 @@ +name: "Sphinx: Render docs" + +on: push + +jobs: + build: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + + - name: Set up conda + uses: conda-incubator/setup-miniconda@v3 + with: + auto-activate-base: true + activate-environment: labcore-docs + environment-file: environment-docs.yml + + - name: Install labcore package + shell: bash -l {0} + run: pip install -e . + + - name: Build HTML + shell: bash -l {0} + run: cd docs && make html + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: html-docs + path: docs/build/html/ + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/build/html \ No newline at end of file diff --git a/.gitignore b/.gitignore index 166b9c8..639af0b 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,9 @@ instance/ # Sphinx documentation docs/_build/ +docs/build/ +docs/autoapi/ +site/ # PyBuilder target/ @@ -117,9 +120,6 @@ venv.bak/ # Rope project settings .ropeproject -# mkdocs documentation -/site - # mypy .mypy_cache/ .dmypy.json diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..b507a95 --- /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 = . +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) \ No newline at end of file diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..554336d Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..29723f5 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,126 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys + +# Add labcore package to path for autodoc +sys.path.insert(0, os.path.abspath('..')) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Labcore' +copyright = '2025-2026, Marcos Frenkel, Wolfgang Pfaff, Cynthia Nolan' +author = 'Marcos Frenkel, Wolfgang Pfaff, Cynthia Nolan' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'myst_parser', # Markdown support + 'sphinx.ext.autodoc', # API documentation from docstrings + 'sphinx.ext.napoleon', # Support for NumPy and Google style docstrings + 'sphinx.ext.viewcode', # Add links to source code + 'autoapi.extension', # Automatic API documentation generation + 'nbsphinx', # Jupyter notebook support + 'sphinx.ext.intersphinx', # Link to other project docs +] + +# MyST Parser configuration +myst_enable_extensions = [ + "colon_fence", # ::: for admonitions + "deflist", # Definition lists + "dollarmath", # Inline and display math using $ + "fieldlist", # Field lists + "html_admonition", # HTML-style admonitions + "html_image", # HTML images + "linkify", # Auto-detect URLs + "replacements", # Text replacements + "smartquotes", # Smart quotes + "substitution", # Variable substitutions + "tasklist", # Task lists +] + +# AutoAPI Configuration (replaces mkdocstrings) +autoapi_type = 'python' +autoapi_dirs = ['../labcore'] +autoapi_options = [ + 'members', + 'undoc-members', + 'show-inheritance', + 'show-module-summary', + 'imported-members', +] +autoapi_keep_files = False +autoapi_add_toctree_entry = True +autoapi_python_class_content = 'both' # Include both class and __init__ docstrings + +# nbsphinx configuration (for Jupyter notebooks) +nbsphinx_execute = 'never' # Don't execute notebooks during build (safer) +nbsphinx_allow_errors = True # Continue building if notebook has errors +nbsphinx_kernel_name = 'python3' + +# Intersphinx configuration (link to other docs) +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'numpy': ('https://numpy.org/doc/stable/', None), + 'pandas': ('https://pandas.pydata.org/docs/', None), + 'xarray': ('https://docs.xarray.dev/en/stable/', None), + 'qcodes': ('https://qcodes.github.io/Qcodes/', None), +} + +templates_path = ['_templates'] +exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints'] + +# -- Internationalization ---------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#internationalization + +language = "en" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_static_path = ['_static'] +html_logo = '_static/logo.png' +html_baseurl = 'https://toolsforexperiments.github.io/labcore/' + +html_theme_options = { + "logo": { + "text": "Labcore", + }, + "external_links": [ + { + "url": "https://toolsforexperiments.github.io/", + "name": "Tools for Experiments", + }, + { + "url": "https://toolsforexperiments.github.io/instrumentserver/", + "name": "Instrumentserver", + }, + { + "url": "https://toolsforexperiments.github.io/plottr/", + "name": "Plottr", + }, + ], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/toolsforexperiments/labcore", + "icon": "fa-brands fa-github", + } + ], + "navbar_start": ["navbar-logo"], + "navbar_center": ["navbar-nav"], + "navbar_end": ["navbar-icon-links", "theme-switcher"], + "footer_start": ["copyright"], + "footer_center": ["sphinx-version"], +} + +# HTML context for custom variables +html_context = { + "default_mode": "auto" # Light/dark theme +} \ No newline at end of file diff --git a/docs/data/analysis_example.md b/docs/data/analysis_example.md new file mode 100644 index 0000000..bb3d04c --- /dev/null +++ b/docs/data/analysis_example.md @@ -0,0 +1,3 @@ +# Analysis + +The following is a placeholder for an analysis guide. More is in the works. \ No newline at end of file diff --git a/docs/data/data_formats.md b/docs/data/data_formats.md index 2e9a038..aee7651 100644 --- a/docs/data/data_formats.md +++ b/docs/data/data_formats.md @@ -504,20 +504,16 @@ Finally, datadict_storage contains 2 module variables, 'DATAFILEXT' and 'TIMESTR ## Reference -### Datadict +API documentation for the data handling modules is auto-generated from source code docstrings. See the [API Reference](../autoapi/labcore/data/index.html) for complete documentation. -::: labcore.data.datadict - options: - docstring_style: sphinx +### DataDict -### Datadict Storage +The `DataDict` class is the main container for in-memory data with metadata support. For full API documentation, see {py:class}`labcore.data.datadict.DataDict`. -::: labcore.data.datadict_storage - options: - docstring_style: sphinx +### DataDict Storage + +Storage utilities for reading and writing DataDict objects to various formats. For full API documentation, see {py:mod}`labcore.data.datadict_storage`. ### Extra Tools -::: labcore.data.tools - options: - docstring_style: sphinx \ No newline at end of file +Additional utilities and helper functions for data handling. For full API documentation, see {py:mod}`labcore.data.tools`. \ No newline at end of file diff --git a/docs/data/index.md b/docs/data/index.md new file mode 100644 index 0000000..0a3ed69 --- /dev/null +++ b/docs/data/index.md @@ -0,0 +1,12 @@ +# Data Handling + +## Data Formats + +```{toctree} +data_formats +``` + +## Analysis +```{toctree} +analysis_example +``` \ No newline at end of file diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 0000000..d7ce0ff --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,10 @@ +# Examples + +```{toctree} + +[//]: # (Introduction to sweeping) +Intro to our Holoviz apps +Holoviz-based plotting in the lab - Primer +hvplot_visualization_guide +Data explorer +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 6091855..337fc78 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,64 @@ --- -template: home.html -title: Labcore +myst: + html_meta: + "description lang=eng": "Labcore - Core software tools for your physics laboratory" +html_theme.sidebar_secondary.remove: true --- + +# Labcore + +:::{warning} +Site under construction +::: + +**Core software tools for your physics laboratory** + +[GitHub Repository](https://github.com/toolsforexperiments/labcore) | [About](about.md) + +## Overview + +Labcore and the whole [Tools For Experiments](https://github.com/toolsforexperiments) are the software efforts of [Pfaff-lab at the University of Illinois at Urbana-Champaign](https://pfaff.physics.illinois.edu/). + +### Full Stack Toolset + +Labcore helps your lab function on all steps of the software stack. From controlling instruments and experiment flow, to final data analysis for publication papers, Labcore provides tools for all of them. + +### Modular Design + +Only use the tools that you need. Labcore modular designs lets you choose which parts of it are the most convenient for your workflow and gets out of the way for the rest. + +### Developed by Physicists + +Labcore is developed by Physicists for real needs happening inside of our lab. + +## Documentation + +```{toctree} +:maxdepth: 2 +:caption: Contents + +instruments/index +measurement/index +data/index +about +``` + +## Examples + +```{toctree} +:maxdepth: 1 +:caption: Jupyter Notebook Examples + +examples/index +``` + +## API Reference + +The API documentation is automatically generated from the source code. + +```{toctree} +:maxdepth: 1 +:caption: API Reference + +autoapi/index +``` \ No newline at end of file diff --git a/docs/instruments/index.md b/docs/instruments/index.md new file mode 100644 index 0000000..3fc100e --- /dev/null +++ b/docs/instruments/index.md @@ -0,0 +1,14 @@ +# Instruments + +## Instrumentserver + +```{toctree} +instrumentserver +instrumentmonitoring +``` + +## QCoDeS Drivers + +```{toctree} +qcodes_instruments/instruments +``` \ No newline at end of file diff --git a/docs/instruments/instrumentmonitoring.md b/docs/instruments/instrumentmonitoring.md index e447386..95b12b0 100644 --- a/docs/instruments/instrumentmonitoring.md +++ b/docs/instruments/instrumentmonitoring.md @@ -2,8 +2,9 @@ The following is a guide to set up a dashboard for the monitoring of instruments. It contains capabilities for data storage, data visualization, and real-time alerts. More information on the tool is provided in the next section. -!!! Note - The following guide assumes the user has the instrumentserver installed and has basic familiarity with it and using config files, labcore installed, basic familiarity with Docker, and a basic understanding of what Grafana and InfluxDB are +:::{note} +The following guide assumes the user has the instrumentserver installed and has basic familiarity with it and using config files, labcore installed, basic familiarity with Docker, and a basic understanding of what Grafana and InfluxDB are +::: ## Overview @@ -47,8 +48,9 @@ In the instrumentserver, for each instrument, the user provides a list of parame The listener is ran on the same computer that is running the Docker containers for Grafana and InfluxDB. It subscribes to the broadcasts from the instrumentservers, and then writes the data to the InfluxDB database. The listener can also be configured to write to a CSV file, however InfluxDB is recommended. -!!! Note - The following portion assumes the user has the instrumentserver installed and labcore installed. +:::{note} +The following portion assumes the user has the instrumentserver installed and labcore installed. +::: ## Quick Start Guide @@ -159,9 +161,10 @@ You should start the instrumentserver using the above commmand in no GUI mode fi $ instrumentserver-detached ``` -!!! Note - The following portion assumes the user has: - - instrumentserver installed +:::{note} +The following portion assumes the user has: +- instrumentserver installed +::: ## The Listener @@ -255,8 +258,9 @@ You can then find the ID number of the process and kill it with: $ kill -15 {INSERT ID} ``` -!!! Note - The following portion assumes the user has the Docker Engine installed and basic familiarity with Docker +:::{note} +The following portion assumes the user has the Docker Engine installed and basic familiarity with Docker +::: ## Docker @@ -365,8 +369,9 @@ You can then close both with the following: ```bash $ sudo docker compose down ``` -!!! Note - Closing will take ~ 10 seconds +:::{note} +Closing will take ~ 10 seconds +::: ## InfluxDB diff --git a/docs/instruments/instrumentserver.md b/docs/instruments/instrumentserver.md index e1f1e6f..f8a5f30 100644 --- a/docs/instruments/instrumentserver.md +++ b/docs/instruments/instrumentserver.md @@ -8,13 +8,15 @@ Instrumentserver also includes a virtual instrument called Parameter Manager, wh single source of truth for various parameters values with a user-friendly graphical interface to facilitate changing parameters. -!!! Note - The instrumentserver lives in its own repository, [here](https://github.com/toolsforexperiments/instrumentserver). - Documentation is here to have a central place for all the documentation of the Tools For Experiments. +:::{note} +The instrumentserver lives in its own repository, [here](https://github.com/toolsforexperiments/instrumentserver). +Documentation is here to have a central place for all the documentation of the Tools For Experiments. +::: -!!! Warning - This guide is not up to date. Some new core features are not currently documented like configuration files and - new features are in development. If you have questions on how to use these, please contact Marcos at: [marcosf2@illinois.edu](). +:::{warning} +This guide is not up to date. Some new core features are not currently documented like configuration files and +new features are in development. If you have questions on how to use these, please contact Marcos at: [marcosf2@illinois.edu](). +::: ## Installation @@ -38,8 +40,9 @@ This will open the GUI of the server and start running it. ![Instrumentserver GUI](img/empty_server.png) -!!! note - The server can be run without a gui by passing the `--gui False` argument. +:::{note} +The server can be run without a gui by passing the `--gui False` argument. +::: By default, instrumentserver listens to the local host IP address (127.0.0.1) and the port 5555. To be able to communicate with the server through other devices in the network we have to specify the IP address we want the server to listen to. @@ -56,9 +59,10 @@ We communicate with the server with Python code. This can be done anywhere that The easiest way of creating a [Client instance](https://github.com/toolsforexperiments/instrumentserver/blob/b9270871364febcfb2ca8ce00b6182ee1762448b/instrumentserver/client/proxy.py#L375) and running the [find_or_create_instrument](https://github.com/toolsforexperiments/instrumentserver/blob/b9270871364febcfb2ca8ce00b6182ee1762448b/instrumentserver/client/proxy.py#L384) method. -!!! note - Remember to pass the instrument specific arguments and keyword arguments necessary for the specific QCoDeS instrument - you are trying to open. +:::{note} +Remember to pass the instrument specific arguments and keyword arguments necessary for the specific QCoDeS instrument +you are trying to open. +::: This will look for the specified instrument with the given name in the server or create it if the instrument does not exist, and return it: @@ -68,9 +72,10 @@ exist, and return it: >>> dummy_instrument = cli.find_or_create_instrument(instrument_class='instrumentserver.testing.dummy_instruments.generic.DummyChannel', name='dummy_instrument') ``` -!!! note - If we are trying to talk to a server running in a different device in the network we need to specify the IP address - and port with the arguments host and port when creating the [Client](https://github.com/toolsforexperiments/instrumentserver/blob/b9270871364febcfb2ca8ce00b6182ee1762448b/instrumentserver/client/proxy.py#L375). +:::{note} +If we are trying to talk to a server running in a different device in the network we need to specify the IP address +and port with the arguments host and port when creating the [Client](https://github.com/toolsforexperiments/instrumentserver/blob/b9270871364febcfb2ca8ce00b6182ee1762448b/instrumentserver/client/proxy.py#L375). +::: After this we can see that the instrument has been created in the server. @@ -85,8 +90,9 @@ from any process and get the dummy_instrument by simply using the [find_or_creat ### Parameter Manager -!!! note - The parameter manager can also be opened from a config file, more instructions on how to do this will come in the near future. +:::{note} +The parameter manager can also be opened from a config file, more instructions on how to do this will come in the near future. +::: Instrumentserver also comes with the virtual instrument Parameter Manager. The Parameter Manager allows us to store values in an instrument inside of the Instrumentserver, allowing us to access them from any process or devices in the same network. @@ -100,9 +106,10 @@ $ instrumentserver-param-manager ``` This will create an instance of the virtual instrument in the Instrumentserver and will open the GUI for the Parameter Manager. -!!! note - At the moment the parameter manager can only be opened from the device that is currently hosting the server. - If you are utilizing a different port, this can be specified by passing the terminal argument `--port` followed by the port. +:::{note} +At the moment the parameter manager can only be opened from the device that is currently hosting the server. +If you are utilizing a different port, this can be specified by passing the terminal argument `--port` followed by the port. +::: We'll simply get an empty window now. The bottom of the window allows us to add arbitrary parameters and values, where dots serve as hierarchy separators (like objects and their children in python). @@ -137,7 +144,8 @@ All of these changes get updated live in the GUI: Changing things in the GUI will also be reflected in the code. -!!! warning - Changing something from the GUI only changes the code if we are calling the parameter manager directly. - If we store a value in a separate variable and then change the GUI, the value in the variable might not get update. - Because of this, we always recommend to call the Parameter Manager directly instead of saving the values in variables. \ No newline at end of file +:::{warning} +Changing something from the GUI only changes the code if we are calling the parameter manager directly. +If we store a value in a separate variable and then change the GUI, the value in the variable might not get update. +Because of this, we always recommend to call the Parameter Manager directly instead of saving the values in variables. +::: \ No newline at end of file diff --git a/docs/instruments/qcodes_instruments/instruments.md b/docs/instruments/qcodes_instruments/instruments.md index e1bae1a..3fbf2d7 100644 --- a/docs/instruments/qcodes_instruments/instruments.md +++ b/docs/instruments/qcodes_instruments/instruments.md @@ -4,7 +4,4 @@ The following are our own QCoDeS drivers that we have developed (or borrowed and ## Specific Drivers -::: labcore.instruments.qcodes_drivers - options: - docstrings_style: sphinx - show_submodules: true +API documentation for our QCoDeS drivers is auto-generated from source code docstrings. See the [API Reference](../../autoapi/labcore/instruments/index.html) for complete documentation of all instrument drivers including {py:mod}`labcore.instruments.qcodes_drivers` and its submodules. diff --git a/docs/measurement/index.md b/docs/measurement/index.md new file mode 100644 index 0000000..979fffd --- /dev/null +++ b/docs/measurement/index.md @@ -0,0 +1,5 @@ +# Measurement + +```{toctree} +sweep +``` \ No newline at end of file diff --git a/docs/measurement/sweep.md b/docs/measurement/sweep.md index 36a3d5b..dccf222 100644 --- a/docs/measurement/sweep.md +++ b/docs/measurement/sweep.md @@ -38,8 +38,9 @@ If ``depends_on=None`` it means this variable is an independent variable. If ``depends_on=['x']``, this variable is dependent on a separate variable with name ``x``. If ``depends_on=[]``, the variable will be automatically assigned as a dependent of all other independents in the same Sweep. -!!! note - [`DataSpec`](#labcore.measurement.record.DataSpec), also contains two more fields: [`unit`](#labcore.measurement.record.DataSpec) and [`types`](#labcore.measurement.record.DataSpec), these however, have no impact in the way the code behaves and are for adding extra metadata for the user. +:::{note} +[`DataSpec`](#labcore.measurement.record.DataSpec), also contains two more fields: [`unit`](#labcore.measurement.record.DataSpec) and [`types`](#labcore.measurement.record.DataSpec), these however, have no impact in the way the code behaves and are for adding extra metadata for the user. +::: While this might seem like a lot of information, its use is very intuitive and easy to use once you get used to it. @@ -85,8 +86,9 @@ This function just makes the recording of data easier to read. >>> measure_stuff(1) {'x': 1, 'y': array([1.60113794])} ``` -!!! note - You can also use the shorter versions of these functions: +:::{note} +You can also use the shorter versions of these functions: +::: * [`ds`](#labcore.measurement.record.ds) for shorter [`DataSpec`](#labcore.measurement.record.DataSpec) * [`indep`](#labcore.measurement.record.indep) for shorter [`independent`](#labcore.measurement.record.independent) @@ -308,9 +310,10 @@ To append two Sweeps or actions we use the ``+`` symbol: {'a': 3, 'b': 0.9812445448108895} ``` -!!! note - [`Sweep.return_none`](#labcore.measurement.sweep.Sweep) controls whether we include data fields that have returned nothing during setting a pointer or executing an action. - Setting it to true (the default) guarantees that each data spec of the sweep has an entry per sweep point, even if it is ``None``. +:::{note} +[`Sweep.return_none`](#labcore.measurement.sweep.Sweep) controls whether we include data fields that have returned nothing during setting a pointer or executing an action. +Setting it to true (the default) guarantees that each data spec of the sweep has an entry per sweep point, even if it is ``None``. +::: For more information see: [Passing Parameters in a Sweep](#passing-parameters-in-a-sweep) section. ### Multiplying @@ -407,9 +410,10 @@ An example of this can be executing measurements on each nested level: {'x': 2, 'a': 0.06159208933324678, 'y': 1, 'b': 0.9064557565446919, 'more_data': 0.8258102740474211} ``` -!!! note - All operators symbols are just there for syntactic brevity. - All three of them have corresponding functions attached to them: +:::{note} +All operators symbols are just there for syntactic brevity. +All three of them have corresponding functions attached to them: +::: * Appending: [`append_sweeps()`](#labcore.measurement.sweep.append_sweeps) * Multiplying: [`zip_sweeps()`](#labcore.measurement.sweep.zip_sweeps) @@ -420,8 +424,9 @@ An example of this can be executing measurements on each nested level: Often times our measurement actions depend on the states of previous steps. Because of that, everything that is generated by **pointers**, **actions** or other Sweeps can be passed on subsequently executed elements. -!!! note - here are two different Sweep configuration related to passing arguments in Sweeps. For more information on them see the [Configuring Sweeps](#configuring-sweeps). +:::{note} +here are two different Sweep configuration related to passing arguments in Sweeps. For more information on them see the [Configuring Sweeps](#configuring-sweeps). +::: ### Positional Arguments @@ -516,9 +521,10 @@ In the example above we have two different sweeps. The **pointer** of the first one is producing **records** which is why we see its value in the test function for ``x``. Since the first sweep is being multiplied to the second sweep we can see how all the **records** (both produced by the **pointer** and **action**) of the first sweep reach the second sweep as keyword arguments, and the non-annotated value of its own **pointer** reaches the action of the second sweep as a positional argument. -!!! warning - When creating **records**, it is very important that each **record** has a *unique* name. Having multiple variables - create **records** with the same names, will make the passing of arguments behave in unpredictable ways. +:::{warning} +When creating **records**, it is very important that each **record** has a *unique* name. Having multiple variables +create **records** with the same names, will make the passing of arguments behave in unpredictable ways. +::: A simple way of renaming conflicting arguments and **records** is to use the combination of ``lambda`` and [`record_as()`](#labcore.measurement.record.record_as): @@ -687,16 +693,18 @@ Data location: data/2022-12-05/2022-12-05T142539_fbfce3e4-my_data/data.ddh5 The measurement has finished successfully and all of the data has been saved. ``` -!!! note - Because this guide has been ported from an older page plottr is not being used anymore, a fix will come. +:::{note} +Because this guide has been ported from an older page plottr is not being used anymore, a fix will come. +::: [`run_and_save_sweep()`](#labcore.measurement.storage.run_and_save_sweep) automatically runs the Sweep indicated, stores the **records** generated by it in a :class:`DataDict ` in a ddh5 file with time tag followed by a random sequence followed by the third argument, in the directory passed by the second argument. Internally the function utilizes the :class:`DDH5Writer ` from `plottr`. For more information on how `plottr` handles data please see: :doc:`../plottr/data`. -!!! note - [`run_and_save_sweep()`](#labcore.measurement.storage.run_and_save_sweep) can save multiple objects to disk by accepting them as extra arguments. - It is a good idea to read over its documentation if you want to be able to save things with it. +:::{note} +[`run_and_save_sweep()`](#labcore.measurement.storage.run_and_save_sweep) can save multiple objects to disk by accepting them as extra arguments. +It is a good idea to read over its documentation if you want to be able to save things with it. +::: Sometimes we have an **action** that we want to run a single time, some kind of setup function or maybe a closing function (or any single **action** in between sweeps). If we also need this **action** to be a Sweep, the function [`once()`](#labcore.measurement.sweep.once) will create a Sweep with no **pointer** that runs an **action** a single time: @@ -725,20 +733,16 @@ closing an instrument ## Reference +API documentation for the measurement modules is auto-generated from source code docstrings. See the [API Reference](../autoapi/labcore/measurement/index.html) for complete documentation. + ### Sweep Module -::: labcore.measurement.sweep - options: - docstring_style: sphinx +The core sweeping functionality for automated measurements. For full API documentation, see {py:mod}`labcore.measurement.sweep`. ### Record Module -::: labcore.measurement.record - options: - docstring_style: sphinx +Low-level recording utilities for measurement data. For full API documentation, see {py:mod}`labcore.measurement.record`. ### Storage Module -::: labcore.measurement.storage - options: - docstring_style: sphinx +Data storage backend for measurement sweeps. For full API documentation, see {py:mod}`labcore.measurement.storage`. diff --git a/docs/overrides/home.html b/docs/overrides/home.html deleted file mode 100644 index 6b00461..0000000 --- a/docs/overrides/home.html +++ /dev/null @@ -1,299 +0,0 @@ - - -{% extends "main.html" %} -{% block tabs %} -{{ super() }} - - - -
-
-
- - - - -
-

⚠ Site under construction ⚠

-

Labcore

-

Core software tools for your physics laboratory

- - GitHub - - - About - -
-
-
-
- - -
-
-

- - Full Stack Toolset -

-

Labcore helps your lab function on all steps of the software stack. - From controlling instruments and experiment flow, to final data analysis for publication papers, Labcore provides tools for all of them.

-
-
-

- - Modular Design -

-

Only use the tools that you need. Labcore modular designs lets you choose which parts of it are the most convenient for your workflow and gets out of the way for the rest.

-
-
-

- - Developed by Physicists -

-

Labcore is developed by Physicists for real needs happening inside of our lab.

-
-
- - -{% endblock %} -{% block content %}{% endblock %} -{% block footer %}{% endblock %} \ No newline at end of file diff --git a/environment-docs.yml b/environment-docs.yml new file mode 100644 index 0000000..3433677 --- /dev/null +++ b/environment-docs.yml @@ -0,0 +1,13 @@ +name: labcore-docs +channels: + - conda-forge +dependencies: + - python=3.13.* + - sphinx + - pydata-sphinx-theme + - myst-parser + - sphinx-autoapi + - nbsphinx + - pandoc + - ipykernel + - linkify-it-py