Skip to content

Commit a6108ae

Browse files
cboulaycboulay
committed
Update deps and add prelim docs
1 parent 5b9795c commit a6108ae

11 files changed

Lines changed: 527 additions & 1 deletion

File tree

‎.github/workflows/docs.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment
18+
concurrency:
19+
group: "pages"
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- name: Install system dependencies
29+
run: sudo apt-get update && sudo apt-get install -y graphviz
30+
31+
- name: Install uv
32+
uses: astral-sh/setup-uv@v6
33+
with:
34+
enable-cache: true
35+
python-version: "3.12"
36+
37+
- name: Install documentation dependencies
38+
run: uv sync --only-group docs
39+
40+
- name: Build documentation
41+
run: |
42+
cd docs
43+
uv run make html
44+
45+
- name: Add .nojekyll file
46+
run: touch docs/build/html/.nojekyll
47+
48+
- name: Add CNAME file for custom domain
49+
run: echo "www.ezmsg.org" > docs/build/html/CNAME
50+
51+
- name: Upload artifact
52+
uses: actions/upload-pages-artifact@v3
53+
with:
54+
path: 'docs/build/html'
55+
56+
deploy:
57+
# Deploy on push to main
58+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
runs-on: ubuntu-latest
63+
needs: build
64+
steps:
65+
- name: Deploy to GitHub Pages
66+
id: deployment
67+
uses: deploy-pages@v4

‎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 = source
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/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/_templates/autosummary/module.rst‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. automodule:: {{ fullname }}
4+
5+
{% block attributes %}
6+
{% if attributes %}
7+
.. rubric:: Module Attributes
8+
9+
.. autosummary::
10+
:toctree:
11+
{% for item in attributes %}
12+
{{ item }}
13+
{%- endfor %}
14+
{% endif %}
15+
{% endblock %}
16+
17+
{% block functions %}
18+
{% if functions %}
19+
.. rubric:: Functions
20+
21+
{% for item in functions %}
22+
.. autofunction:: {{ item }}
23+
{%- endfor %}
24+
{% endif %}
25+
{% endblock %}
26+
27+
{% block classes %}
28+
{% if classes %}
29+
.. rubric:: Classes
30+
31+
{% for item in classes %}
32+
.. autoclass:: {{ item }}
33+
:members:
34+
:undoc-members:
35+
:show-inheritance:
36+
:special-members: __init__
37+
{%- endfor %}
38+
{% endif %}
39+
{% endblock %}
40+
41+
{% block exceptions %}
42+
{% if exceptions %}
43+
.. rubric:: Exceptions
44+
45+
{% for item in exceptions %}
46+
.. autoexception:: {{ item }}
47+
:members:
48+
:show-inheritance:
49+
{%- endfor %}
50+
{% endif %}
51+
{% endblock %}
52+
53+
{% block modules %}
54+
{% if modules %}
55+
.. rubric:: Modules
56+
57+
.. autosummary::
58+
:toctree:
59+
:recursive:
60+
{% for item in modules %}
61+
{{ item }}
62+
{%- endfor %}
63+
{% endif %}
64+
{% endblock %}

‎docs/source/api/index.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
API Reference
2+
=============
3+
4+
This page contains auto-generated API reference documentation.
5+
6+
.. autosummary::
7+
:toctree: generated
8+
:recursive:
9+
:template: autosummary/module.rst
10+
11+
ezmsg.event

‎docs/source/conf.py‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
3+
import os
4+
import sys
5+
6+
# Add the source directory to the path
7+
sys.path.insert(0, os.path.abspath("../../src"))
8+
9+
# -- Project information --------------------------
10+
11+
project = "ezmsg.event"
12+
copyright = "2024, ezmsg Contributors"
13+
author = "ezmsg Contributors"
14+
15+
# The version is managed by hatch-vcs and stored in __version__.py
16+
try:
17+
from ezmsg.event.__version__ import version as release
18+
except ImportError:
19+
release = "unknown"
20+
21+
# For display purposes, extract the base version without git commit info
22+
version = release.split("+")[0] if release != "unknown" else release
23+
24+
# -- General configuration --------------------------
25+
26+
extensions = [
27+
"sphinx.ext.autodoc",
28+
"sphinx.ext.autosummary",
29+
"sphinx.ext.napoleon",
30+
"sphinx.ext.intersphinx",
31+
"sphinx.ext.viewcode",
32+
"sphinx.ext.duration",
33+
"sphinx_copybutton",
34+
"myst_parser", # For markdown files
35+
]
36+
37+
templates_path = ["_templates"]
38+
source_suffix = {
39+
".rst": "restructuredtext",
40+
".md": "markdown",
41+
}
42+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
43+
44+
# The toctree master document
45+
master_doc = "index"
46+
47+
# -- Autodoc configuration ------------------------------
48+
49+
# Auto-generate API docs
50+
autosummary_generate = True
51+
autosummary_imported_members = False
52+
autodoc_typehints = "description"
53+
autodoc_member_order = "bysource"
54+
autodoc_typehints_format = "short"
55+
python_use_unqualified_type_names = True
56+
autodoc_default_options = {
57+
"members": True,
58+
"member-order": "bysource",
59+
"special-members": "__init__",
60+
"undoc-members": True,
61+
"show-inheritance": True,
62+
}
63+
64+
# Don't show the full module path in the docs
65+
add_module_names = False
66+
67+
# -- Intersphinx configuration --------------------------
68+
69+
intersphinx_mapping = {
70+
"python": ("https://docs.python.org/3/", None),
71+
"numpy": ("https://numpy.org/doc/stable/", None),
72+
"ezmsg": ("https://www.ezmsg.org/ezmsg/", None),
73+
"ezmsg.sigproc": ("https://www.ezmsg.org/ezmsg-sigproc/", None),
74+
}
75+
intersphinx_disabled_domains = ["std"]
76+
77+
# -- Options for HTML output -----------------------------
78+
79+
html_theme = "pydata_sphinx_theme"
80+
html_static_path = ["_static"]
81+
82+
# Set the base URL for the documentation
83+
html_baseurl = "https://www.ezmsg.org/ezmsg-event/"
84+
85+
html_theme_options = {
86+
"logo": {
87+
"text": f"ezmsg.event {version}",
88+
"link": "https://ezmsg.org", # Link back to main site
89+
},
90+
"header_links_before_dropdown": 4,
91+
"navbar_start": ["navbar-logo"],
92+
"navbar_end": ["theme-switcher", "navbar-icon-links"],
93+
"icon_links": [
94+
{
95+
"name": "GitHub",
96+
"url": "https://github.com/ezmsg-org/ezmsg-event",
97+
"icon": "fa-brands fa-github",
98+
},
99+
{
100+
"name": "ezmsg.org",
101+
"url": "https://www.ezmsg.org",
102+
"icon": "fa-solid fa-house",
103+
},
104+
],
105+
}
106+
107+
# Timestamp is inserted at every page bottom in this strftime format.
108+
html_last_updated_fmt = "%Y-%m-%d"
109+
110+
# -- Options for linkcode -----------------------------
111+
112+
branch = "main"
113+
code_url = f"https://github.com/ezmsg-org/ezmsg-event/blob/{branch}/"
114+
115+
116+
def linkcode_resolve(domain, info):
117+
if domain != "py":
118+
return None
119+
if not info["module"]:
120+
return None
121+
filename = info["module"].replace(".", "/")
122+
return f"{code_url}src/{filename}.py"

‎docs/source/index.rst‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
ezmsg.event
2+
===========
3+
4+
ezmsg namespace package for working with signal events like neural spikes and heartbeats.
5+
6+
Overview
7+
--------
8+
9+
``ezmsg-event`` ezmsg namespace package for working with signal events like neural spikes and heartbeats.
10+
11+
Key features:
12+
13+
* **Event detection** - Detect and track signal events in neural data
14+
* **Spike handling** - Process neural spike events
15+
* **Heartbeat tracking** - Monitor physiological heartbeat events
16+
* **Event timestamps** - Precise timing for event occurrences
17+
18+
19+
Installation
20+
------------
21+
22+
Install from PyPI:
23+
24+
.. code-block:: bash
25+
26+
pip install ezmsg-event
27+
28+
Or install the latest development version:
29+
30+
.. code-block:: bash
31+
32+
pip install git+https://github.com/ezmsg-org/ezmsg-event@main
33+
34+
Dependencies
35+
^^^^^^^^^^^^
36+
37+
Core dependencies:
38+
39+
* ``ezmsg``
40+
* ``numpy``
41+
* ``ezmsg.sigproc``
42+
43+
Quick Start
44+
-----------
45+
46+
For general ezmsg tutorials and guides, visit `ezmsg.org <https://www.ezmsg.org>`_.
47+
48+
For package-specific documentation:
49+
50+
* **API Reference** - See :doc:`api/index` for complete API documentation
51+
* **README** - See the `GitHub repository <https://github.com/ezmsg-org/ezmsg-event>`_ for usage examples
52+
53+
Documentation
54+
-------------
55+
56+
.. toctree::
57+
:maxdepth: 2
58+
:caption: Contents:
59+
60+
api/index
61+
62+
63+
Indices and tables
64+
------------------
65+
66+
* :ref:`genindex`
67+
* :ref:`modindex`

0 commit comments

Comments
 (0)