Skip to content

Commit 614b49c

Browse files
marcosfrenkelmarcosfrenkel
authored
Switching to sphinx (#99)
* Moved from mkdocs to sphinx * Tweaked general site organization
1 parent ec6a017 commit 614b49c

File tree

18 files changed

+397
-382
lines changed

18 files changed

+397
-382
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/analysis_example.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Analysis
2+
3+
The following is a placeholder for an analysis guide. More is in the works.

‎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/data/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Data Handling
2+
3+
## Data Formats
4+
5+
```{toctree}
6+
data_formats
7+
```
8+
9+
## Analysis
10+
```{toctree}
11+
analysis_example
12+
```

‎docs/examples/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Examples
2+
3+
```{toctree}
4+
5+
[//]: # (Introduction to sweeping)
6+
Intro to our Holoviz apps
7+
Holoviz-based plotting in the lab - Primer
8+
hvplot_visualization_guide
9+
Data explorer
10+
```

‎docs/index.md‎

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,64 @@
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/index
41+
measurement/index
42+
data/index
43+
about
44+
```
45+
46+
## Examples
47+
48+
```{toctree}
49+
:maxdepth: 1
50+
:caption: Jupyter Notebook Examples
51+
52+
examples/index
53+
```
54+
55+
## API Reference
56+
57+
The API documentation is automatically generated from the source code.
58+
59+
```{toctree}
60+
:maxdepth: 1
61+
:caption: API Reference
62+
63+
autoapi/index
64+
```

0 commit comments

Comments
 (0)