Skip to content

Commit 7d8a96b

Browse files
PierreRaybautPierreRaybaut
committed
Add documentation for DataLab-Kernel
- Created API documentation for the Workspace class and its components. - Added development setup guide and contribution guidelines. - Introduced user guide sections covering installation, getting started, features, and overview. - Included example notebooks demonstrating basic usage, live mode, and persistence. - Updated pyproject.toml to include documentation dependencies.
1 parent ce82b31 commit 7d8a96b

23 files changed

Lines changed: 1972 additions & 0 deletions

‎doc/_static/DataLab-Banner.svg‎

Lines changed: 104 additions & 0 deletions
Loading

‎doc/_static/DataLab-Kernel-Banner.svg‎

Lines changed: 10 additions & 0 deletions
Loading

‎doc/_static/custom.css‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
/* Custom CSS for DataLab-Kernel documentation */
2+
3+
/* Dark/light mode support for images */
4+
.dark-light {
5+
filter: invert(0);
6+
}
7+
8+
html[data-theme="dark"] .dark-light {
9+
filter: invert(1);
10+
}
11+
12+
/* Remove scaling on logo */
13+
.no-scaled-link img {
14+
max-width: 100%;
15+
height: auto;
16+
}

‎doc/api/index.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
.. _api:
2+
3+
API Reference
4+
=============
5+
6+
The public API of DataLab-Kernel provides a simple interface for
7+
scientific data processing in Jupyter notebooks.
8+
9+
.. list-table::
10+
:header-rows: 1
11+
:align: left
12+
13+
* - Module
14+
- Purpose
15+
16+
* - :mod:`datalab_kernel`
17+
- Main entry point with ``Workspace``, ``Plotter``, and ``WorkspaceMode``
18+
19+
* - :mod:`datalab_kernel.objects`
20+
- Data objects (``SignalObj``, ``ImageObj``) and creation functions
21+
(``create_signal``, ``create_image``) - re-exported from Sigima
22+
23+
* - :mod:`datalab_kernel.workspace`
24+
- Workspace implementation with backend abstraction
25+
26+
27+
.. toctree::
28+
:maxdepth: 2
29+
:caption: API Modules:
30+
31+
workspace
32+
objects
33+
plotter

‎doc/api/objects.rst‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
.. _api_objects:
2+
3+
Objects
4+
=======
5+
6+
Data objects for signals and images, re-exported from Sigima.
7+
8+
.. automodule:: datalab_kernel.objects
9+
:members:
10+
:undoc-members:
11+
:show-inheritance:
12+
13+
SignalObj
14+
---------
15+
16+
The ``SignalObj`` class represents 1D signal data with X/Y arrays,
17+
optional error bars, metadata, units, and labels.
18+
19+
See `Sigima SignalObj documentation <https://sigima.readthedocs.io/en/latest/api/objects.html>`_
20+
for complete details.
21+
22+
Basic usage:
23+
24+
.. code-block:: python
25+
26+
from datalab_kernel.objects import SignalObj, create_signal
27+
import numpy as np
28+
29+
# Using create_signal (recommended)
30+
signal = create_signal(
31+
"My Signal",
32+
np.linspace(0, 10, 100),
33+
np.sin(np.linspace(0, 10, 100)),
34+
units=("s", "V"),
35+
labels=("Time", "Voltage"),
36+
)
37+
38+
# Direct instantiation
39+
signal = SignalObj()
40+
signal.set_xydata(x_array, y_array)
41+
signal.title = "My Signal"
42+
43+
44+
ImageObj
45+
--------
46+
47+
The ``ImageObj`` class represents 2D image data with metadata,
48+
coordinate system, units, and labels.
49+
50+
See `Sigima ImageObj documentation <https://sigima.readthedocs.io/en/latest/api/objects.html>`_
51+
for complete details.
52+
53+
Basic usage:
54+
55+
.. code-block:: python
56+
57+
from datalab_kernel.objects import ImageObj, create_image
58+
import numpy as np
59+
60+
# Using create_image (recommended)
61+
image = create_image(
62+
"My Image",
63+
np.random.rand(256, 256),
64+
units=("mm", "mm", "counts"),
65+
labels=("X", "Y", "Intensity"),
66+
)
67+
68+
# Direct instantiation
69+
image = ImageObj()
70+
image.data = data_2d
71+
image.title = "My Image"
72+
73+
74+
create_signal
75+
-------------
76+
77+
Factory function for creating signal objects.
78+
79+
.. code-block:: python
80+
81+
create_signal(
82+
title: str,
83+
x: np.ndarray | None = None,
84+
y: np.ndarray | None = None,
85+
dx: np.ndarray | None = None,
86+
dy: np.ndarray | None = None,
87+
metadata: dict | None = None,
88+
units: tuple[str, str] | None = None,
89+
labels: tuple[str, str] | None = None,
90+
) -> SignalObj
91+
92+
**Parameters:**
93+
94+
- ``title``: Signal title
95+
- ``x``: X data array
96+
- ``y``: Y data array
97+
- ``dx``: X error bars (optional)
98+
- ``dy``: Y error bars (optional)
99+
- ``metadata``: Additional metadata dictionary
100+
- ``units``: Tuple of (x_unit, y_unit)
101+
- ``labels``: Tuple of (x_label, y_label)
102+
103+
104+
create_image
105+
------------
106+
107+
Factory function for creating image objects.
108+
109+
.. code-block:: python
110+
111+
create_image(
112+
title: str,
113+
data: np.ndarray | None = None,
114+
metadata: dict | None = None,
115+
units: tuple | None = None,
116+
labels: tuple | None = None,
117+
) -> ImageObj
118+
119+
**Parameters:**
120+
121+
- ``title``: Image title
122+
- ``data``: 2D data array
123+
- ``metadata``: Additional metadata dictionary
124+
- ``units``: Tuple of (x_unit, y_unit, z_unit)
125+
- ``labels``: Tuple of (x_label, y_label, z_label)

‎doc/api/plotter.rst‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
.. _api_plotter:
2+
3+
Plotter
4+
=======
5+
6+
The ``Plotter`` class provides visualization for workspace objects.
7+
8+
.. automodule:: datalab_kernel.plotter
9+
:members:
10+
:undoc-members:
11+
:show-inheritance:
12+
13+
Usage
14+
-----
15+
16+
.. code-block:: python
17+
18+
from datalab_kernel import Workspace, Plotter
19+
20+
workspace = Workspace()
21+
plotter = Plotter(workspace)
22+
23+
# Add some objects
24+
workspace.add("signal", signal_obj)
25+
workspace.add("image", image_obj)
26+
27+
# Plot by name
28+
plotter.plot("signal")
29+
plotter.plot("image")
30+
31+
Signal Plotting
32+
---------------
33+
34+
Signals are plotted as line plots:
35+
36+
.. code-block:: python
37+
38+
plotter.plot("my_signal")
39+
40+
# With custom options
41+
plotter.plot("my_signal", color="red", linewidth=2)
42+
43+
Image Plotting
44+
--------------
45+
46+
Images are displayed as 2D colormaps:
47+
48+
.. code-block:: python
49+
50+
plotter.plot("my_image")
51+
52+
# With colormap and colorbar
53+
plotter.plot("my_image", cmap="viridis", colorbar=True)
54+
55+
# With specific value range
56+
plotter.plot("my_image", vmin=0, vmax=100)

‎doc/api/workspace.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
.. _api_workspace:
2+
3+
Workspace
4+
=========
5+
6+
The ``Workspace`` class is the central API for managing data objects.
7+
8+
.. automodule:: datalab_kernel.workspace
9+
:members:
10+
:undoc-members:
11+
:show-inheritance:
12+
13+
WorkspaceMode
14+
-------------
15+
16+
.. autoclass:: datalab_kernel.workspace.WorkspaceMode
17+
:members:
18+
:undoc-members:
19+
20+
Workspace Class
21+
---------------
22+
23+
.. autoclass:: datalab_kernel.workspace.Workspace
24+
:members:
25+
:undoc-members:
26+
:show-inheritance:
27+
28+
Backend Classes
29+
---------------
30+
31+
.. autoclass:: datalab_kernel.workspace.StandaloneBackend
32+
:members:
33+
:undoc-members:
34+
:show-inheritance:
35+
36+
.. autoclass:: datalab_kernel.workspace.LiveBackend
37+
:members:
38+
:undoc-members:
39+
:show-inheritance:

‎doc/conf.py‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
2+
3+
# pylint: skip-file
4+
5+
import os
6+
import sys
7+
8+
sys.path.insert(0, os.path.abspath(".."))
9+
10+
import datalab_kernel
11+
12+
# -- Project information -----------------------------------------------------
13+
14+
project = "DataLab-Kernel"
15+
author = "DataLab Platform Developers"
16+
copyright = "2025, DataLab Platform Developers"
17+
release = datalab_kernel.__version__
18+
19+
# -- General configuration ---------------------------------------------------
20+
21+
extensions = [
22+
"sphinx.ext.intersphinx",
23+
"sphinx.ext.napoleon",
24+
"sphinx.ext.mathjax",
25+
"sphinx.ext.githubpages",
26+
"sphinx.ext.viewcode",
27+
"sphinx.ext.autodoc",
28+
"myst_nb", # Markdown and notebook support
29+
"sphinx_design",
30+
"sphinx_copybutton",
31+
]
32+
33+
# MyST-NB configuration
34+
nb_execution_mode = "off" # Don't re-execute notebooks during build
35+
nb_execution_timeout = 180 # Timeout for notebook execution (if enabled)
36+
37+
templates_path = ["_templates"]
38+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
39+
40+
# Suppress some warnings
41+
suppress_warnings = ["config.cache"]
42+
43+
# -- Options for HTML output -------------------------------------------------
44+
html_theme = "pydata_sphinx_theme"
45+
html_title = project
46+
html_logo = "_static/DataLab-Kernel-Banner.svg"
47+
html_favicon = "_static/favicon.ico"
48+
html_show_sourcelink = False
49+
50+
html_theme_options = {
51+
"show_toc_level": 2,
52+
"github_url": "https://github.com/DataLab-Platform/DataLab-Kernel/",
53+
"logo": {
54+
"text": f"v{datalab_kernel.__version__}",
55+
},
56+
"icon_links": [
57+
{
58+
"name": "PyPI",
59+
"url": "https://pypi.org/project/datalab-kernel",
60+
"icon": "_static/pypi.svg",
61+
"type": "local",
62+
"attributes": {"target": "_blank"},
63+
},
64+
{
65+
"name": "DataLab",
66+
"url": "https://datalab-platform.com",
67+
"icon": "_static/DataLab.svg",
68+
"type": "local",
69+
"attributes": {"target": "_blank"},
70+
},
71+
],
72+
}
73+
html_static_path = ["_static"]
74+
75+
# -- Options for LaTeX output ------------------------------------------------
76+
latex_logo = "_static/DataLab-Kernel-Banner.png"
77+
78+
# -- Options for sphinx-intl package -----------------------------------------
79+
locale_dirs = ["locale/"]
80+
gettext_compact = False
81+
gettext_location = False
82+
83+
# -- Options for autodoc extension -------------------------------------------
84+
autodoc_default_options = {
85+
"members": True,
86+
"member-order": "bysource",
87+
}
88+
89+
# -- Options for intersphinx extension ---------------------------------------
90+
intersphinx_mapping = {
91+
"python": ("https://docs.python.org/3", None),
92+
"numpy": ("https://numpy.org/doc/stable/", None),
93+
"sigima": ("https://sigima.readthedocs.io/en/latest/", None),
94+
"datalab": ("https://datalab-platform.readthedocs.io/en/latest/", None),
95+
"ipykernel": ("https://ipykernel.readthedocs.io/en/stable/", None),
96+
}

0 commit comments

Comments
 (0)