From a9316f0b37b603ad7c505a32082666cf745737cf Mon Sep 17 00:00:00 2001 From: Chadwick Boulay Date: Fri, 31 Oct 2025 02:06:59 -0400 Subject: [PATCH 1/2] Update deps and add prelim docs --- .github/workflows/docs.yml | 67 ++++++++++ docs/Makefile | 20 +++ docs/make.bat | 35 +++++ docs/source/_templates/autosummary/module.rst | 64 +++++++++ docs/source/api/index.rst | 11 ++ docs/source/conf.py | 121 ++++++++++++++++++ docs/source/index.rst | 69 ++++++++++ pyproject.toml | 17 ++- 8 files changed, 402 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/_templates/autosummary/module.rst create mode 100644 docs/source/api/index.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..96b25d1 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,67 @@ +name: Documentation + +on: + push: + branches: + - main + pull_request: + branches: + - main + 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 + + - name: Install system dependencies + run: sudo apt-get update && sudo apt-get install -y graphviz + + - name: Install uv + uses: astral-sh/setup-uv@v6 + with: + enable-cache: true + python-version: "3.12" + + - name: Install documentation dependencies + 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: Add CNAME file for custom domain + run: echo "www.ezmsg.org" > docs/build/html/CNAME + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/build/html' + + deploy: + # Deploy on push to main + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + 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: deploy-pages@v4 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/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 0000000..fd632b4 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,64 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: Module Attributes + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: Functions + + {% for item in functions %} + .. autofunction:: {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: Classes + + {% for item in classes %} + .. autoclass:: {{ item }} + :members: + :undoc-members: + :show-inheritance: + :special-members: __init__ + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: Exceptions + + {% for item in exceptions %} + .. autoexception:: {{ item }} + :members: + :show-inheritance: + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 0000000..c1445a1 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,11 @@ +API Reference +============= + +This page contains auto-generated API reference documentation. + +.. autosummary:: + :toctree: generated + :recursive: + :template: autosummary/module.rst + + ezmsg.tools diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..e998fd5 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,121 @@ +# 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.tools" +copyright = "2024, ezmsg Contributors" +author = "ezmsg Contributors" + +# The version is managed by hatch-vcs and stored in __version__.py +try: + from ezmsg.tools.__version__ import version as release +except ImportError: + release = "unknown" + +# For display purposes, extract the base version without git commit info +version = release.split("+")[0] if release != "unknown" else release + +# -- General configuration -------------------------- + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.duration", + "sphinx_copybutton", + "myst_parser", # For markdown files +] + +templates_path = ["_templates"] +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The toctree master document +master_doc = "index" + +# -- Autodoc configuration ------------------------------ + +# Auto-generate API docs +autosummary_generate = True +autosummary_imported_members = False +autodoc_typehints = "description" +autodoc_member_order = "bysource" +autodoc_typehints_format = "short" +python_use_unqualified_type_names = True +autodoc_default_options = { + "members": True, + "member-order": "bysource", + "special-members": "__init__", + "undoc-members": True, + "show-inheritance": 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), + "ezmsg": ("https://www.ezmsg.org/ezmsg/", 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-tools/" + +html_theme_options = { + "logo": { + "text": f"ezmsg.tools {version}", + "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-tools", + "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-tools/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..a34d4ab --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,69 @@ +ezmsg.tools +=========== + +Tools to visualize running graphs and data in ezmsg. + +Overview +-------- + +``ezmsg-tools`` tools to visualize running graphs and data in ezmsg. + +Key features: + +* **Graph visualization** - Visualize ezmsg graph topologies +* **Data visualization** - Real-time data plotting and monitoring +* **Debug tools** - Tools for debugging ezmsg pipelines + + +.. note:: + The data visualization is highly fragile. Expect bugs. + + +Installation +------------ + +Install from PyPI: + +.. code-block:: bash + + pip install ezmsg-tools + +Or install the latest development version: + +.. code-block:: bash + + pip install git+https://github.com/ezmsg-org/ezmsg-tools@main + +Dependencies +^^^^^^^^^^^^ + +Core dependencies: + +* ``ezmsg`` +* ``various visualization libraries`` + +Quick Start +----------- + +For general ezmsg tutorials and guides, visit `ezmsg.org `_. + +For package-specific documentation: + +* **API Reference** - See :doc:`api/index` for complete API documentation +* **README** - See the `GitHub repository `_ for usage examples + +Documentation +------------- + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api/index + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` diff --git a/pyproject.toml b/pyproject.toml index 6e5539b..f604ccc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,16 +12,29 @@ dependencies = [ "numpy>=1.26.0", ] -[project.optional-dependencies] +[dependency-groups] dev = [ - "ruff>=0.8.1", + {include-group = "lint"}, + {include-group = "test"}, "scipy>=1.14.1", "ezmsg-sigproc>=2.0.0", ] +lint = [ + "ruff>=0.12.9", +] test = [ "ezmsg-sigproc>=1.6.0", "pytest>=8.3.3", ] +docs = [ + "sphinx>=7.0", + "sphinx-autodoc-typehints", + "sphinx-copybutton", + "pydata-sphinx-theme", + "myst-parser", +] + +[project.optional-dependencies] perfmon = [ "dash-extensions>=1.0.19", "dash>=2.18.2", From 190a750c9a0065f063b32e9af16fd5980c1950bb Mon Sep 17 00:00:00 2001 From: Chadwick Boulay Date: Fri, 31 Oct 2025 02:28:25 -0400 Subject: [PATCH 2/2] Fix GHA docs workflow --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 96b25d1..aaed34e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -64,4 +64,4 @@ jobs: steps: - name: Deploy to GitHub Pages id: deployment - uses: deploy-pages@v4 + uses: actions/deploy-pages@v4