Skip to content

Commit d59a24f

Browse files
marcosfrenkelmarcosfrenkel
committed
Moved from mkdocs to sphinx
1 parent ec6a017 commit d59a24f

File tree

12 files changed

+359
-83
lines changed

12 files changed

+359
-83
lines changed

‎.github/workflows/sphinx.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: "Sphinx: Render docs"
2+
3+
on: push
4+
5+
jobs:
6+
build:
7+
runs-on: ubuntu-latest
8+
permissions:
9+
contents: write
10+
steps:
11+
- uses: actions/checkout@v4
12+
with:
13+
persist-credentials: false
14+
15+
- name: Set up conda
16+
uses: conda-incubator/setup-miniconda@v3
17+
with:
18+
auto-activate-base: true
19+
activate-environment: labcore-docs
20+
environment-file: environment-docs.yml
21+
22+
- name: Install labcore package
23+
shell: bash -l {0}
24+
run: pip install -e .
25+
26+
- name: Build HTML
27+
shell: bash -l {0}
28+
run: cd docs && make html
29+
30+
- name: Upload artifacts
31+
uses: actions/upload-artifact@v4
32+
with:
33+
name: html-docs
34+
path: docs/build/html/
35+
36+
- name: Deploy
37+
uses: peaceiris/actions-gh-pages@v3
38+
if: github.ref == 'refs/heads/main'
39+
with:
40+
github_token: ${{ secrets.GITHUB_TOKEN }}
41+
publish_dir: docs/build/html

‎.gitignore‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,9 @@ instance/
7070

7171
# Sphinx documentation
7272
docs/_build/
73+
docs/build/
74+
docs/autoapi/
75+
site/
7376

7477
# PyBuilder
7578
target/
@@ -117,9 +120,6 @@ venv.bak/
117120
# Rope project settings
118121
.ropeproject
119122

120-
# mkdocs documentation
121-
/site
122-
123123
# mypy
124124
.mypy_cache/
125125
.dmypy.json

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/logo.png‎

141 KB
Loading

‎docs/conf.py‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
import os
7+
import sys
8+
9+
# Add labcore package to path for autodoc
10+
sys.path.insert(0, os.path.abspath('..'))
11+
12+
# -- Project information -----------------------------------------------------
13+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
14+
15+
project = 'Labcore'
16+
copyright = '2025-2026, Marcos Frenkel, Wolfgang Pfaff, Cynthia Nolan'
17+
author = 'Marcos Frenkel, Wolfgang Pfaff, Cynthia Nolan'
18+
19+
# -- General configuration ---------------------------------------------------
20+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
21+
22+
extensions = [
23+
'myst_parser', # Markdown support
24+
'sphinx.ext.autodoc', # API documentation from docstrings
25+
'sphinx.ext.napoleon', # Support for NumPy and Google style docstrings
26+
'sphinx.ext.viewcode', # Add links to source code
27+
'autoapi.extension', # Automatic API documentation generation
28+
'nbsphinx', # Jupyter notebook support
29+
'sphinx.ext.intersphinx', # Link to other project docs
30+
]
31+
32+
# MyST Parser configuration
33+
myst_enable_extensions = [
34+
"colon_fence", # ::: for admonitions
35+
"deflist", # Definition lists
36+
"dollarmath", # Inline and display math using $
37+
"fieldlist", # Field lists
38+
"html_admonition", # HTML-style admonitions
39+
"html_image", # HTML images
40+
"linkify", # Auto-detect URLs
41+
"replacements", # Text replacements
42+
"smartquotes", # Smart quotes
43+
"substitution", # Variable substitutions
44+
"tasklist", # Task lists
45+
]
46+
47+
# AutoAPI Configuration (replaces mkdocstrings)
48+
autoapi_type = 'python'
49+
autoapi_dirs = ['../labcore']
50+
autoapi_options = [
51+
'members',
52+
'undoc-members',
53+
'show-inheritance',
54+
'show-module-summary',
55+
'imported-members',
56+
]
57+
autoapi_keep_files = False
58+
autoapi_add_toctree_entry = True
59+
autoapi_python_class_content = 'both' # Include both class and __init__ docstrings
60+
61+
# nbsphinx configuration (for Jupyter notebooks)
62+
nbsphinx_execute = 'never' # Don't execute notebooks during build (safer)
63+
nbsphinx_allow_errors = True # Continue building if notebook has errors
64+
nbsphinx_kernel_name = 'python3'
65+
66+
# Intersphinx configuration (link to other docs)
67+
intersphinx_mapping = {
68+
'python': ('https://docs.python.org/3', None),
69+
'numpy': ('https://numpy.org/doc/stable/', None),
70+
'pandas': ('https://pandas.pydata.org/docs/', None),
71+
'xarray': ('https://docs.xarray.dev/en/stable/', None),
72+
'qcodes': ('https://qcodes.github.io/Qcodes/', None),
73+
}
74+
75+
templates_path = ['_templates']
76+
exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
77+
78+
# -- Internationalization ----------------------------------------------------
79+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#internationalization
80+
81+
language = "en"
82+
83+
# -- Options for HTML output -------------------------------------------------
84+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
85+
86+
html_theme = "pydata_sphinx_theme"
87+
html_static_path = ['_static']
88+
html_logo = '_static/logo.png'
89+
html_baseurl = 'https://toolsforexperiments.github.io/labcore/'
90+
91+
html_theme_options = {
92+
"logo": {
93+
"text": "Labcore",
94+
},
95+
"external_links": [
96+
{
97+
"url": "https://toolsforexperiments.github.io/",
98+
"name": "Tools for Experiments",
99+
},
100+
{
101+
"url": "https://toolsforexperiments.github.io/instrumentserver/",
102+
"name": "Instrumentserver",
103+
},
104+
{
105+
"url": "https://toolsforexperiments.github.io/plottr/",
106+
"name": "Plottr",
107+
},
108+
],
109+
"icon_links": [
110+
{
111+
"name": "GitHub",
112+
"url": "https://github.com/toolsforexperiments/labcore",
113+
"icon": "fa-brands fa-github",
114+
}
115+
],
116+
"navbar_start": ["navbar-logo"],
117+
"navbar_center": ["navbar-nav"],
118+
"navbar_end": ["navbar-icon-links", "theme-switcher"],
119+
"footer_start": ["copyright"],
120+
"footer_center": ["sphinx-version"],
121+
}
122+
123+
# HTML context for custom variables
124+
html_context = {
125+
"default_mode": "auto" # Light/dark theme
126+
}

‎docs/data/data_formats.md‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -504,20 +504,16 @@ Finally, datadict_storage contains 2 module variables, 'DATAFILEXT' and 'TIMESTR
504504

505505
## Reference
506506

507-
### Datadict
507+
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.
508508

509-
::: labcore.data.datadict
510-
options:
511-
docstring_style: sphinx
509+
### DataDict
512510

513-
### Datadict Storage
511+
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`.
514512

515-
::: labcore.data.datadict_storage
516-
options:
517-
docstring_style: sphinx
513+
### DataDict Storage
514+
515+
Storage utilities for reading and writing DataDict objects to various formats. For full API documentation, see {py:mod}`labcore.data.datadict_storage`.
518516

519517
### Extra Tools
520518

521-
::: labcore.data.tools
522-
options:
523-
docstring_style: sphinx
519+
Additional utilities and helper functions for data handling. For full API documentation, see {py:mod}`labcore.data.tools`.

‎docs/index.md‎

Lines changed: 68 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,70 @@
11
---
2-
template: home.html
3-
title: Labcore
2+
myst:
3+
html_meta:
4+
"description lang=eng": "Labcore - Core software tools for your physics laboratory"
5+
html_theme.sidebar_secondary.remove: true
46
---
7+
8+
# Labcore
9+
10+
:::{warning}
11+
Site under construction
12+
:::
13+
14+
**Core software tools for your physics laboratory**
15+
16+
[GitHub Repository](https://github.com/toolsforexperiments/labcore) | [About](about.md)
17+
18+
## Overview
19+
20+
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/).
21+
22+
### Full Stack Toolset
23+
24+
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.
25+
26+
### Modular Design
27+
28+
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.
29+
30+
### Developed by Physicists
31+
32+
Labcore is developed by Physicists for real needs happening inside of our lab.
33+
34+
## Documentation
35+
36+
```{toctree}
37+
:maxdepth: 2
38+
:caption: Contents
39+
40+
instruments/instrumentserver
41+
instruments/instrumentmonitoring
42+
instruments/qcodes_instruments/instruments
43+
measurement/sweep
44+
data/data_formats
45+
about
46+
```
47+
48+
## Examples
49+
50+
```{toctree}
51+
:maxdepth: 1
52+
:caption: Jupyter Notebook Examples
53+
54+
examples/Introduction to sweeping
55+
examples/Intro to our Holoviz apps
56+
examples/Holoviz-based plotting in the lab - Primer
57+
examples/hvplot_visualization_guide
58+
examples/Data explorer
59+
```
60+
61+
## API Reference
62+
63+
The API documentation is automatically generated from the source code.
64+
65+
```{toctree}
66+
:maxdepth: 1
67+
:caption: API Reference
68+
69+
autoapi/index
70+
```

‎docs/instruments/instrumentmonitoring.md‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22

33
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.
44

5-
!!! Note
6-
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
5+
:::{note}
6+
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
7+
:::
78

89
## Overview
910

@@ -47,8 +48,9 @@ In the instrumentserver, for each instrument, the user provides a list of parame
4748

4849
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.
4950

50-
!!! Note
51-
The following portion assumes the user has the instrumentserver installed and labcore installed.
51+
:::{note}
52+
The following portion assumes the user has the instrumentserver installed and labcore installed.
53+
:::
5254

5355
## Quick Start Guide
5456

@@ -159,9 +161,10 @@ You should start the instrumentserver using the above commmand in no GUI mode fi
159161
$ instrumentserver-detached
160162
```
161163

162-
!!! Note
163-
The following portion assumes the user has:
164-
- instrumentserver installed
164+
:::{note}
165+
The following portion assumes the user has:
166+
- instrumentserver installed
167+
:::
165168

166169
## The Listener
167170

@@ -255,8 +258,9 @@ You can then find the ID number of the process and kill it with:
255258
$ kill -15 {INSERT ID}
256259
```
257260

258-
!!! Note
259-
The following portion assumes the user has the Docker Engine installed and basic familiarity with Docker
261+
:::{note}
262+
The following portion assumes the user has the Docker Engine installed and basic familiarity with Docker
263+
:::
260264

261265
## Docker
262266

@@ -365,8 +369,9 @@ You can then close both with the following:
365369
```bash
366370
$ sudo docker compose down
367371
```
368-
!!! Note
369-
Closing will take ~ 10 seconds
372+
:::{note}
373+
Closing will take ~ 10 seconds
374+
:::
370375

371376
## InfluxDB
372377

0 commit comments

Comments
 (0)