diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..a176bd3 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,65 @@ +name: Documentation + +on: + push: + branches: + - main + tags: + - 'v*' + pull_request: + branches: + - dev + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Needed for hatch-vcs to determine version + + - name: Install uv + uses: astral-sh/setup-uv@v6 + with: + enable-cache: true + python-version: "3.12" + + - name: Install the project + run: uv sync --only-group docs + + - name: Build documentation + run: | + cd docs + uv run make html + + - name: Add .nojekyll file + run: touch docs/build/html/.nojekyll + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/build/html' + + deploy: + # Only deploy on push to main or release tags + if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')) + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 6e32a49..f0ef468 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,5 @@ Processing units include dimensionality reduction, linear regression, and classi This ezmsg namespace package is still highly experimental and under active development. It is not yet available on PyPI, so you will need to install it from source. The easiest way to do this is to use the `pip` command to install the package directly from GitHub: ```bash -pip install git+ssh://git@github.com/ezmsg-org/ezmsg-learn -``` - -Note that this package depends on a specific version of `ezmsg-sigproc` (specifically, [this branch]("70-use-protocols-for-axisarray-transformers")) that has yet to be merged and released. This may conflict with your project's separate dependency on ezmsg-sigproc. However, this specific version of ezmsg-sigproc should be backwards compatible with its main branch, so in your project you can modify the dependency on ezmsg-sigproc to point to the new branch. e.g., - -```bash -pip install git+ssh://git@github.com/ezmsg-org/ezmsg-sigproc@70-use-protocols-for-axisarray-transformers +pip install git+https://github.com/ezmsg-org/ezmsg-learn ``` diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /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 = source +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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..9534b01 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/api/generated/ezmsg.learn.dim_reduce.adaptive_decomp.rst b/docs/source/api/generated/ezmsg.learn.dim_reduce.adaptive_decomp.rst new file mode 100644 index 0000000..47685c3 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.dim_reduce.adaptive_decomp.rst @@ -0,0 +1,21 @@ +ezmsg.learn.dim\_reduce.adaptive\_decomp +======================================== + +.. automodule:: ezmsg.learn.dim_reduce.adaptive_decomp + + + .. rubric:: Classes + + .. autosummary:: + + AdaptiveDecompSettings + AdaptiveDecompState + AdaptiveDecompTransformer + BaseAdaptiveDecompUnit + IncrementalPCASettings + IncrementalPCATransformer + IncrementalPCAUnit + MiniBatchNMFSettings + MiniBatchNMFTransformer + MiniBatchNMFUnit + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.dim_reduce.incremental_decomp.rst b/docs/source/api/generated/ezmsg.learn.dim_reduce.incremental_decomp.rst new file mode 100644 index 0000000..2fe7c40 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.dim_reduce.incremental_decomp.rst @@ -0,0 +1,14 @@ +ezmsg.learn.dim\_reduce.incremental\_decomp +=========================================== + +.. automodule:: ezmsg.learn.dim_reduce.incremental_decomp + + + .. rubric:: Classes + + .. autosummary:: + + IncrementalDecompSettings + IncrementalDecompTransformer + IncrementalDecompUnit + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.linear_model.adaptive_linear_regressor.rst b/docs/source/api/generated/ezmsg.learn.linear_model.adaptive_linear_regressor.rst new file mode 100644 index 0000000..7311345 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.linear_model.adaptive_linear_regressor.rst @@ -0,0 +1,6 @@ +ezmsg.learn.linear\_model.adaptive\_linear\_regressor +===================================================== + +.. automodule:: ezmsg.learn.linear_model.adaptive_linear_regressor + + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.linear_model.cca.rst b/docs/source/api/generated/ezmsg.learn.linear_model.cca.rst new file mode 100644 index 0000000..825932e --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.linear_model.cca.rst @@ -0,0 +1,6 @@ +ezmsg.learn.linear\_model.cca +============================= + +.. automodule:: ezmsg.learn.linear_model.cca + + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.linear_model.linear_regressor.rst b/docs/source/api/generated/ezmsg.learn.linear_model.linear_regressor.rst new file mode 100644 index 0000000..f2addc4 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.linear_model.linear_regressor.rst @@ -0,0 +1,6 @@ +ezmsg.learn.linear\_model.linear\_regressor +=========================================== + +.. automodule:: ezmsg.learn.linear_model.linear_regressor + + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.linear_model.sgd.rst b/docs/source/api/generated/ezmsg.learn.linear_model.sgd.rst new file mode 100644 index 0000000..5708e5b --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.linear_model.sgd.rst @@ -0,0 +1,6 @@ +ezmsg.learn.linear\_model.sgd +============================= + +.. automodule:: ezmsg.learn.linear_model.sgd + + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.linear_model.slda.rst b/docs/source/api/generated/ezmsg.learn.linear_model.slda.rst new file mode 100644 index 0000000..c3961c0 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.linear_model.slda.rst @@ -0,0 +1,6 @@ +ezmsg.learn.linear\_model.slda +============================== + +.. automodule:: ezmsg.learn.linear_model.slda + + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.model.cca.rst b/docs/source/api/generated/ezmsg.learn.model.cca.rst new file mode 100644 index 0000000..50a4555 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.model.cca.rst @@ -0,0 +1,12 @@ +ezmsg.learn.model.cca +===================== + +.. automodule:: ezmsg.learn.model.cca + + + .. rubric:: Classes + + .. autosummary:: + + IncrementalCCA + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.model.mlp.rst b/docs/source/api/generated/ezmsg.learn.model.mlp.rst new file mode 100644 index 0000000..5319b40 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.model.mlp.rst @@ -0,0 +1,12 @@ +ezmsg.learn.model.mlp +===================== + +.. automodule:: ezmsg.learn.model.mlp + + + .. rubric:: Classes + + .. autosummary:: + + MLP + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.model.refit_kalman.rst b/docs/source/api/generated/ezmsg.learn.model.refit_kalman.rst new file mode 100644 index 0000000..27c1dff --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.model.refit_kalman.rst @@ -0,0 +1,12 @@ +ezmsg.learn.model.refit\_kalman +=============================== + +.. automodule:: ezmsg.learn.model.refit_kalman + + + .. rubric:: Classes + + .. autosummary:: + + RefitKalmanFilter + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.model.rnn.rst b/docs/source/api/generated/ezmsg.learn.model.rnn.rst new file mode 100644 index 0000000..3dd23b3 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.model.rnn.rst @@ -0,0 +1,12 @@ +ezmsg.learn.model.rnn +===================== + +.. automodule:: ezmsg.learn.model.rnn + + + .. rubric:: Classes + + .. autosummary:: + + RNNModel + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.model.transformer.rst b/docs/source/api/generated/ezmsg.learn.model.transformer.rst new file mode 100644 index 0000000..afa95c6 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.model.transformer.rst @@ -0,0 +1,12 @@ +ezmsg.learn.model.transformer +============================= + +.. automodule:: ezmsg.learn.model.transformer + + + .. rubric:: Classes + + .. autosummary:: + + TransformerModel + \ No newline at end of file diff --git a/docs/source/api/generated/ezmsg.learn.util.rst b/docs/source/api/generated/ezmsg.learn.util.rst new file mode 100644 index 0000000..77a9717 --- /dev/null +++ b/docs/source/api/generated/ezmsg.learn.util.rst @@ -0,0 +1,21 @@ +ezmsg.learn.util +================ + +.. automodule:: ezmsg.learn.util + + + .. rubric:: Functions + + .. autosummary:: + + get_regressor + + .. rubric:: Classes + + .. autosummary:: + + AdaptiveLinearRegressor + ClassifierMessage + RegressorType + StaticLinearRegressor + \ No newline at end of file diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 0000000..bae3e68 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,56 @@ +API Reference +============= + +This page contains the complete API reference for ``ezmsg.learn``. + +.. contents:: Modules + :local: + :depth: 1 + +Dimensionality Reduction +------------------------- + +.. autosummary:: + :toctree: generated + :recursive: + + ezmsg.learn.dim_reduce.incremental_decomp + ezmsg.learn.dim_reduce.adaptive_decomp + +Linear Models +------------- + +.. note:: + The ``ezmsg.learn.linear_model`` module is deprecated. Please use ``ezmsg.learn.process`` instead. + +.. autosummary:: + :toctree: generated + :recursive: + + ezmsg.learn.linear_model.adaptive_linear_regressor + ezmsg.learn.linear_model.linear_regressor + ezmsg.learn.linear_model.sgd + ezmsg.learn.linear_model.slda + ezmsg.learn.linear_model.cca + +Models +------ + +.. autosummary:: + :toctree: generated + :recursive: + + ezmsg.learn.model.cca + ezmsg.learn.model.mlp + ezmsg.learn.model.rnn + ezmsg.learn.model.transformer + ezmsg.learn.model.refit_kalman + +Utilities +--------- + +.. autosummary:: + :toctree: generated + :recursive: + + ezmsg.learn.util diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..46814c9 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,112 @@ +# Configuration file for the Sphinx documentation builder. + +import os +import sys + +# Add the source directory to the path +sys.path.insert(0, os.path.abspath("../../src")) + +# -- Project information -------------------------- + +project = "ezmsg.learn" +copyright = "2024, ezmsg Contributors" +author = "ezmsg Contributors" + +# The version is managed by hatch-vcs and stored in __version__.py +try: + from ezmsg.learn.__version__ import version as release +except ImportError: + release = "unknown" + +version = release + +# -- General configuration -------------------------- + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.duration", + "sphinx_autodoc_typehints", + "sphinx_copybutton", +] + +templates_path = ["_templates"] +source_suffix = [".rst"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The toctree master document +master_doc = "index" + +# -- Autodoc configuration ------------------------------ + +# Auto-generate API docs +autosummary_generate = True +autodoc_typehints = "description" +autodoc_member_order = "bysource" +autodoc_typehints_format = "short" +python_use_unqualified_type_names = True + +# Don't show the full module path in the docs +add_module_names = False + +# -- Intersphinx configuration -------------------------- + +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "torch": ("https://pytorch.org/docs/stable/", None), + "sklearn": ("https://scikit-learn.org/stable/", None), + "ezmsg": ("https://www.ezmsg.org/ezmsg/", None), + "ezmsg.sigproc": ("https://www.ezmsg.org/ezmsg-sigproc/", None), +} +intersphinx_disabled_domains = ["std"] + +# -- Options for HTML output ----------------------------- + +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] + +# Set the base URL for the documentation +html_baseurl = "https://www.ezmsg.org/ezmsg-learn/" + +html_theme_options = { + "logo": { + "text": "ezmsg.learn", + "link": "https://ezmsg.org", # Link back to main site + }, + "header_links_before_dropdown": 4, + "navbar_start": ["navbar-logo"], + "navbar_end": ["theme-switcher", "navbar-icon-links"], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/ezmsg-org/ezmsg-learn", + "icon": "fa-brands fa-github", + }, + { + "name": "ezmsg.org", + "url": "https://www.ezmsg.org", + "icon": "fa-solid fa-house", + }, + ], +} + +# Timestamp is inserted at every page bottom in this strftime format. +html_last_updated_fmt = "%Y-%m-%d" + +# -- Options for linkcode ----------------------------- + +branch = "main" +code_url = f"https://github.com/ezmsg-org/ezmsg-learn/blob/{branch}/" + + +def linkcode_resolve(domain, info): + if domain != "py": + return None + if not info["module"]: + return None + filename = info["module"].replace(".", "/") + return f"{code_url}src/{filename}.py" diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..55f575d --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,66 @@ +ezmsg.learn +============ + +Machine learning modules for the `ezmsg `_ framework. + +.. note:: + **This package is experimental and under active development.** + +Overview +-------- + +``ezmsg-learn`` provides machine learning processing units designed for streaming signals in the ezmsg framework. + +Modules include: + +* **Linear models** - Linear regression, SLDA, CCA, SGD +* **Non-linear models** - Multi-layer perceptrons (MLP) +* **Dimensionality reduction** - Incremental PCA and other decomposition methods +* **Utilities** - Helper functions for ML workflows + +Most modules support both: + +* **Offline initialization** with known weights +* **Online adaptation** with streaming labeled data + +Installation +------------ + +Install directly from GitHub: + +.. code-block:: bash + + pip install git+https://github.com/ezmsg-org/ezmsg-learn + +Dependencies +^^^^^^^^^^^^ + +This package requires: + +* ``ezmsg`` - Core ezmsg framework +* ``ezmsg-sigproc`` - Signal processing extensions +* ``numpy`` - Numerical computing +* ``scikit-learn`` - Machine learning utilities +* ``torch`` - Deep learning framework +* ``river`` - Online machine learning + +Quick Start +----------- + +For general ezmsg tutorials and guides, visit `ezmsg.org `_. + +For package-specific examples and usage, see the :doc:`api/index` documentation. + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Contents: + + api/index + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` diff --git a/pyproject.toml b/pyproject.toml index 4d0ed33..cb9d4a9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,6 +28,12 @@ test = [ "hmmlearn>=0.3.3", "pytest>=8.4.1", ] +docs = [ + "sphinx>=8.1.3", + "pydata-sphinx-theme", + "sphinx_autodoc_typehints>=3.0.0", + "sphinx_copybutton", +] [build-system] requires = ["hatchling", "hatch-vcs"]