Switching to sphinx

.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

.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

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)

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
+}

docs/data/analysis_example.md

@@ -0,0 +1,3 @@
+# Analysis
+
+The following is a placeholder for an analysis guide. More is in the works.

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
+Additional utilities and helper functions for data handling. For full API documentation, see {py:mod}`labcore.data.tools`.

docs/data/index.md

@@ -0,0 +1,12 @@
+# Data Handling
+
+## Data Formats
+
+```{toctree}
+data_formats
+```
+
+## Analysis
+```{toctree}
+analysis_example
+```

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
+```

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
+```

docs/instruments/index.md

@@ -0,0 +1,14 @@
+# Instruments
+
+## Instrumentserver
+
+```{toctree}
+instrumentserver
+instrumentmonitoring
+```
+
+## QCoDeS Drivers
+
+```{toctree}
+qcodes_instruments/instruments
+```