Skip to content

Commit 3c15d2e

Browse files
cboulaycboulay
committed
Update project for build
1 parent 92345fa commit 3c15d2e

2 files changed

Lines changed: 124 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# ezmsg.org Documentation Site
2+
3+
This repository hosts the main documentation site for the ezmsg ecosystem, published at [ezmsg.org](https://ezmsg.org).
4+
5+
## Overview
6+
7+
This is an **organization-level documentation site** that provides:
8+
- Getting started guides and tutorials
9+
- Conceptual explanations of ezmsg architecture
10+
- How-to guides for common use cases
11+
- Links to API documentation for all ezmsg packages
12+
- Developer guides for contributors
13+
- Information about ezmsg extensions
14+
15+
## Documentation Architecture
16+
17+
The ezmsg documentation is distributed across multiple repositories:
18+
19+
- **ezmsg.org** (this repo) → General documentation, tutorials, guides
20+
- **ezmsg.org/ezmsg** → Core ezmsg API reference (from [ezmsg repo](https://github.com/ezmsg-org/ezmsg))
21+
- **ezmsg.org/ezmsg-sigproc** → Signal processing API (from [ezmsg-sigproc repo](https://github.com/ezmsg-org/ezmsg-sigproc))
22+
- **ezmsg.org/ezmsg-lsl** → LSL integration API (from [ezmsg-lsl repo](https://github.com/ezmsg-org/ezmsg-lsl))
23+
- **ezmsg.org/ezmsg-learn** → Machine learning API (from [ezmsg-learn repo](https://github.com/ezmsg-org/ezmsg-learn))
24+
25+
Each package repository builds its own API documentation using autodoc from docstrings, while this repository contains the narrative documentation.
26+
27+
## Building Documentation Locally
28+
29+
### Prerequisites
30+
- Python 3.10 or higher
31+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip
32+
33+
### Build Steps
34+
35+
1. **Clone the repository**
36+
```bash
37+
git clone https://github.com/ezmsg-org/ezmsg-org.github.io.git
38+
cd ezmsg-org.github.io
39+
```
40+
41+
2. **Install dependencies**
42+
```bash
43+
uv sync --only-group docs
44+
```
45+
46+
3. **Build the documentation**
47+
```bash
48+
cd docs
49+
uv run make html
50+
```
51+
52+
4. **View the documentation**
53+
Open `docs/build/html/index.html` in your browser
54+
55+
### Clean Build
56+
To rebuild from scratch:
57+
```bash
58+
cd docs
59+
uv run make clean
60+
uv run make html
61+
```
62+
63+
## Contributing
64+
65+
Contributions to improve the documentation are welcome! Please:
66+
67+
1. Fork this repository
68+
2. Create a feature branch
69+
3. Make your changes
70+
4. Test the build locally
71+
5. Submit a pull request
72+
73+
### Content Guidelines
74+
75+
- **Tutorials**: Step-by-step guides for beginners
76+
- **How-tos**: Task-oriented guides for specific problems
77+
- **Explanations**: Conceptual information about ezmsg architecture
78+
- **Reference**: Links to API documentation (do not duplicate API docs here)
79+
80+
## Deployment
81+
82+
Documentation is automatically built and deployed via GitHub Actions:
83+
84+
- **Push to `main`**: Automatically deploys to ezmsg.org
85+
- **Pull requests**: Build-only (no deployment) for validation
86+
87+
The workflow is defined in `.github/workflows/docs.yml`.
88+
89+
## Directory Structure
90+
91+
```
92+
ezmsg-org.github.io/
93+
├── .github/
94+
│ └── workflows/
95+
│ └── docs.yml # GitHub Actions workflow
96+
├── docs/
97+
│ ├── source/
98+
│ │ ├── conf.py # Sphinx configuration
99+
│ │ ├── index.rst # Homepage
100+
│ │ ├── tutorials/ # Tutorial content
101+
│ │ ├── how-tos/ # How-to guides
102+
│ │ ├── explanations/ # Conceptual docs
103+
│ │ ├── reference/ # API links and glossary
104+
│ │ ├── developer/ # Contributor guides
105+
│ │ └── extensions/ # Extension information
106+
│ ├── Makefile
107+
│ └── make.bat
108+
├── pyproject.toml # Python dependencies
109+
└── README.md # This file
110+
```
111+
112+
## License
113+
114+
This documentation is part of the ezmsg project. See [LICENSE](LICENSE) for details.
115+
116+
## Support
117+
118+
- **Issues**: Report documentation issues in this repository's [issue tracker](https://github.com/ezmsg-org/ezmsg-org.github.io/issues)
119+
- **Code issues**: Report to the respective package repository
120+
- **Community**: Join discussions in the [ezmsg organization](https://github.com/ezmsg-org)
121+
122+
## Acknowledgments
123+
124+
The ezmsg project is supported by Johns Hopkins University (JHU), the JHU Applied Physics Laboratory (APL), and the Wyss Center for Bio and Neuro Engineering.

‎pyproject.toml‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,6 @@
22
name = "ezmsg-docs"
33
version = "1.0.0"
44
description = "Documentation for the ezmsg ecosystem"
5-
authors = [
6-
{ name = "Griffin Milsap", email = "griffin.milsap@gmail.com" },
7-
{ name = "Preston Peranich", email = "pperanich@gmail.com" },
8-
{ name = "Chadwick Boulay", email = "chadwick.boulay@gmail.com" },
9-
{ name = "Konrad Pilch", email = "kpilch@blackrockneuro.com" },
10-
]
11-
license = { file = "LICENSE" }
12-
readme = "README.md"
135
requires-python = ">=3.10"
146
dependencies = []
157

@@ -25,7 +17,3 @@ docs = [
2517
"sphinx_copybutton",
2618
"sphinx_design",
2719
]
28-
29-
[build-system]
30-
requires = ["hatchling"]
31-
build-backend = "hatchling.build"

0 commit comments

Comments
 (0)