Skip to content

Commit 6f16e41

Browse files
srivarrasrivarra
authored
docs: update docs to zensical (#378)
* docs: update docs to zensical Signed-off-by: Sricharan Reddy Varra <sricharan.varra@biohub.org> * ci: update to use zensical on pr workflow Signed-off-by: Sricharan Reddy Varra <sricharan.varra@biohub.org> * docs: fix overloads and indents in docs Signed-off-by: Sricharan Reddy Varra <sricharan.varra@biohub.org> * test: removed specific doc check in test Signed-off-by: Sricharan Reddy Varra <sricharan.varra@biohub.org> --------- Signed-off-by: Sricharan Reddy Varra <sricharan.varra@biohub.org>
1 parent f4bf0e4 commit 6f16e41

42 files changed

Lines changed: 1303 additions & 1345 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs.yml‎

Lines changed: 16 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,36 @@
1-
name: documentation
2-
1+
name: Documentation
32
on:
43
push:
5-
branches: ["main"]
6-
7-
# Allows you to run this workflow manually from the Actions tab
8-
workflow_dispatch:
9-
4+
branches: [main]
5+
pull_request:
6+
branches: [main]
107
permissions:
118
contents: read
129
pages: write
1310
id-token: write
14-
15-
concurrency:
16-
group: "pages"
17-
cancel-in-progress: true
18-
1911
jobs:
2012
build:
2113
runs-on: ubuntu-latest
2214
steps:
23-
- name: Checkout
24-
uses: actions/checkout@v4
15+
- uses: actions/checkout@v5
16+
- uses: astral-sh/setup-uv@v7
2517
with:
26-
fetch-depth: 0
27-
28-
- name: Setup Pages
29-
id: pages
30-
uses: actions/configure-pages@v3
31-
32-
- name: Install uv
33-
uses: astral-sh/setup-uv@v7
34-
35-
- name: Set up Python
36-
run: uv python install 3.11
37-
38-
- name: Install dependencies
39-
run: |
40-
uv sync --group doc
41-
# temporary fix for sphinx-polyversion
42-
uv pip install --force-reinstall git+https://github.com/ziw-liu/sphinx-polyversion.git@iohub-staging
43-
- name: Set environment
44-
run: |
45-
REPO_OWNER="${GITHUB_REPOSITORY%%/*}"
46-
REPO_NAME="${GITHUB_REPOSITORY#*/}"
47-
echo "GITHUB_PAGES_URL=https://$REPO_OWNER.github.io/$REPO_NAME" >> $GITHUB_ENV
48-
49-
- name: Build the docs
50-
run: |
51-
echo $GITHUB_PAGES_URL
52-
uv run make build -C docs
53-
touch docs/build/.nojekyll
54-
55-
- name: Upload build artifacts
56-
uses: actions/upload-pages-artifact@v3
18+
python-version: "3.11"
19+
enable-cache: true
20+
- run: uv sync --group doc
21+
- run: uv run zensical build --clean
22+
- uses: actions/upload-pages-artifact@v4
5723
with:
58-
path: "./docs/build"
24+
path: site
5925

6026
deploy:
27+
if: github.ref == 'refs/heads/main'
28+
needs: build
6129
environment:
6230
name: github-pages
6331
url: ${{ steps.deployment.outputs.page_url }}
64-
permissions:
65-
pages: write
66-
id-token: write
6732
runs-on: ubuntu-latest
68-
needs: build
6933
steps:
70-
- name: Deploy to GitHub Pages
34+
- uses: actions/configure-pages@v5
35+
- uses: actions/deploy-pages@v4
7136
id: deployment
72-
uses: actions/deploy-pages@v4

‎.github/workflows/pr.yml‎

Lines changed: 6 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -41,24 +41,13 @@ jobs:
4141
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
4242
run: uv run pytest -v --cov=./ --cov-report=xml
4343

44-
# this checks that docs build and examples run
45-
# but does not deploy to GH Pages
4644
docs:
4745
runs-on: ubuntu-latest
4846
steps:
4947
- uses: actions/checkout@v4
50-
51-
- name: Install uv
52-
uses: astral-sh/setup-uv@v7
53-
54-
- name: Set up Python
55-
run: uv python install 3.11
56-
57-
- name: Install dependencies
58-
run: |
59-
uv sync --group doc
60-
# temporary fix for sphinx-polyversion
61-
uv pip install --force-reinstall git+https://github.com/ziw-liu/sphinx-polyversion.git@iohub-staging
62-
63-
- name: Test docs build
64-
run: uv run sphinx-polyversion docs/poly.py -vvv --local
48+
- uses: astral-sh/setup-uv@v7
49+
with:
50+
python-version: "3.11"
51+
enable-cache: true
52+
- run: uv sync --group doc
53+
- run: uv run zensical build --clean

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ __pycache__/
1515
# C extensions
1616
*.so
1717

18+
# Zensical docs build output
19+
site/
20+
1821
# Distribution / packaging
1922
.Python
2023
build/

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ The project uses [dependency groups](https://docs.astral.sh/uv/concepts/projects
114114
|-------|---------|
115115
| `test` | Testing tools (pytest, hypothesis, etc.) |
116116
| `acquire-zarr` | Acquire-zarr reader (requires glibc 2.35+) |
117-
| `doc` | Documentation (sphinx, etc.) |
117+
| `doc` | Documentation (zensical, mkdocstrings, etc.) |
118118
| `pre-commit` | Pre-commit hooks |
119119
| `dev` | Includes test, acquire-zarr, doc, pre-commit (installed by default via `uv sync`) |
120120

@@ -124,38 +124,24 @@ Then make the changes and [track them with Git](https://docs.github.com/en/get-s
124124

125125
### Developing documentation
126126

127-
#### Prerequisites
127+
Documentation is built with [Zensical](https://zensical.org). Configuration lives in `zensical.toml`.
128128

129-
Install the [forked version of `sphinx-polyversion`](https://github.com/ziw-liu/sphinx-polyversion/tree/iohub-staging) (temporary fix for compatibility):
129+
#### Building the HTML version locally
130130

131131
```shell
132-
uv pip install --force-reinstall git+https://github.com/ziw-liu/sphinx-polyversion.git@iohub-staging
132+
uv sync --group doc
133+
uv run zensical serve
133134
```
134135

135-
#### Building the HTML version locally
136+
This starts a local dev server at `http://localhost:8000` with live reloading.
136137

137-
Inside the `docs/` folder:
138+
To build static HTML:
138139

139140
```shell
140-
make clean
141-
uv run sphinx-polyversion poly.py -vvv --local
141+
uv run zensical build --clean
142142
```
143143

144-
Generated HTML documentation can be found in the `build/` directory.
145-
146-
#### Writing examples
147-
148-
Example scripts in the `docs/examples` directory
149-
are automatically compiled to RST with `sphinx-gallery`
150-
in the `docs/source/auto_examples` directory.
151-
Files that start with `run_` in the file name
152-
are executed during the build,
153-
and output (stdout, matplotlib plot) are rendered in HTML.
154-
155-
They can also be executed as plain Python scripts
156-
or interactive code blocks in some IDEs (VS Code, PyCharm, Spyder etc.).
157-
158-
See the [syntax documentation](https://sphinx-gallery.github.io/stable/syntax.html).
144+
Generated HTML documentation can be found in the `site/` directory.
159145

160146
### Testing
161147

‎docs/Makefile‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎docs/api/converter.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Convert TIFF to OME-Zarr
2+
3+
!!! note
4+
There is also a CLI command for conversion.
5+
See the [CLI Reference](../cli.md) or run `iohub convert --help`.
6+
7+
::: iohub.convert.TIFFConverter

‎docs/api/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# API Reference
2+
3+
## OME-NGFF (OME-Zarr)
4+
5+
- [OME-NGFF](ngff.md) - Core OME-Zarr reading and writing
6+
7+
## Readers
8+
9+
- [Readers](readers.md) - TIFF-based format readers (Micro-Manager, NDTiff, ClearControl, PTI)
10+
11+
## Conversion
12+
13+
- [Converter](converter.md) - TIFF to OME-Zarr conversion

‎docs/api/ngff.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# OME-NGFF (OME-Zarr)
2+
3+
## Convenience
4+
5+
::: iohub.open_ome_zarr
6+
options:
7+
show_overloads: false
8+
9+
## NGFF Nodes
10+
11+
::: iohub.ngff.NGFFNode
12+
13+
::: iohub.ngff.Position
14+
15+
::: iohub.ngff.TiledPosition
16+
17+
::: iohub.ngff.Plate
18+
19+
::: iohub.ngff.ImageArray

‎docs/api/readers.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Readers
2+
3+
## Read multi-FOV datasets
4+
5+
::: iohub.read_images
6+
7+
## MMStack OME-TIFF
8+
9+
::: iohub.mmstack.MMStack
10+
11+
::: iohub.mmstack.MMOmeTiffFOV
12+
13+
## NDTiff
14+
15+
::: iohub.ndtiff.NDTiffDataset
16+
17+
::: iohub.ndtiff.NDTiffFOV
18+
19+
## ClearControl
20+
21+
::: iohub.clearcontrol.ClearControlFOV
22+
23+
## MM TIFF Sequence (deprecated)
24+
25+
::: iohub._deprecated.singlepagetiff.MicromanagerSequenceReader
26+
27+
## PTI TIFF (deprecated)
28+
29+
::: iohub._deprecated.upti.UPTIReader

‎docs/cli.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# CLI Reference
2+
3+
::: mkdocs-click
4+
:module: iohub.cli.cli
5+
:command: cli
6+
:prog_name: iohub
7+
:depth: 1
8+
:style: table

0 commit comments

Comments
 (0)
⚡