docs: adding docs (#149)

* docs: adding docs

* docs: tweaks

* docs: fixup

.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: ci
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - run: pip install .[docs]
+      - run: mkdocs gh-deploy --force

.pre-commit-config.yaml

@@ -21,7 +21,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.272
+    rev: v0.0.275
     hooks:
       - id: ruff
         args: [--fix]
@@ -37,9 +37,17 @@ repos:
       - id: validate-pyproject
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.3.0
+    rev: v1.4.0
     hooks:
       - id: mypy
         files: "^src/"
         exclude: scripts
         additional_dependencies: [numpy, lxml-stubs]
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.5
+    hooks:
+      - id: codespell
+        exclude: CHANGELOG.md
+        args:
+          - "-L=nd2,nd,pevents"

README.md

@@ -111,11 +111,11 @@ f.events()          # returns tabular "Recorded Data" view from in NIS Elements/
 
 # allll the metadata we can find...
 # no attempt made to standardize or parse it
-# look in here if you're searching for metdata that isn't exposed in the above
+# look in here if you're searching for metadata that isn't exposed in the above
 # but try not to rely on it, as it's not guaranteed to be stable
 f.unstructured_metadata()
 
-f.close()           # don't forget to close when not using a contet manager!
+f.close()           # don't forget to close when not using a context manager!
 f.closed            # boolean, whether the file is closed
 ```
 

docs/API/nd2.md

@@ -0,0 +1,5 @@
+# nd2
+
+::: nd2
+    options:
+        filters: ["!^Binary", "!^_"]

docs/API/nd2_binary.md

@@ -0,0 +1,8 @@
+# nd2 (binary masks)
+
+::: nd2
+    options:
+        filters: ["!^_"]
+        members:
+            - BinaryLayers
+            - BinaryLayer

docs/API/structures.md

@@ -0,0 +1,5 @@
+# nd2.structures
+
+::: nd2.structures
+    options:
+        show_if_no_docstring: true

docs/index.md

@@ -0,0 +1,138 @@
+# Quickstart
+
+[![License](https://img.shields.io/pypi/l/nd2.svg?style=flat-square&color=yellow)](https://github.com/tlambert03/nd2/raw/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nd2?style=flat-square&color=yellow)](https://pypi.org/project/nd2)
+[![PyPI](https://img.shields.io/pypi/v/nd2.svg?style=flat-square&color=yellow)](https://pypi.org/project/nd2)
+[![Conda](https://img.shields.io/conda/v/conda-forge/nd2?style=flat-square&color=yellow)](https://anaconda.org/conda-forge/nd2)
+
+.nd2 (Nikon NIS Elements) file reader.
+
+Features complete metadata retrieval, and many array outputs, including
+[`to_dask()`][nd2.ND2File.to_dask] and [`to_xarray()`][nd2.ND2File.to_xarray]
+options for lazy and/or annotated arrays (in addition to numpy arrays).
+
+This library is thoroughly tested against many nd2 files with the goal of
+maximizing compatibility and data extraction. (If you find an nd2 file that
+fails in any way, please [open an
+issue](https://github.com/tlambert03/nd2/issues/new) with the file!)
+
+!!! Note
+    This library is not affiliated with Nikon in any way, but we are
+    grateful for assistance from the SDK developers at [Laboratory
+    Imaging](https://www.lim.cz).
+
+## Installation
+
+From pip:
+
+```sh
+pip install nd2
+```
+
+From conda:
+
+```sh
+conda install -c conda-forge nd2
+```
+
+### With legacy nd2 file support
+
+Legacy nd2 (JPEG2000) files are also supported, but require `imagecodecs`.  To
+install with support for these files use the `legacy` extra:
+
+```sh
+pip install nd2[legacy]
+```
+
+### Faster XML parsing
+
+Much of the metadata in the file stored as XML.  If found in the environment,
+`nd2` will use [`lxml`](https://pypi.org/project/lxml/) which is faster than the
+built-in `xml` module.  To install with support for `lxml` use:
+
+```sh
+pip install nd2 lxml
+```
+
+## Usage overview
+
+For complete usage details, see the [API](API/nd2.md)
+
+### Reading nd2 files into arrays
+
+To quickly read an nd2 file into a numpy, dask, or xarray array,
+use `nd2.imread()`:
+
+```python
+import nd2
+
+# read to numpy array
+my_array = nd2.imread('some_file.nd2')
+
+# read to dask array
+my_array = nd2.imread('some_file.nd2', dask=True)
+
+# read to xarray
+my_array = nd2.imread('some_file.nd2', xarray=True)
+
+# read file to dask-xarray
+my_array = nd2.imread('some_file.nd2', xarray=True, dask=True)
+```
+
+### Extracting metadata
+
+If you want to get metadata, then use the [`nd2.ND2File`][] class directly:
+
+```python
+myfile = nd2.ND2File('some_file.nd2')
+```
+
+!!! tip
+    It's best to use it as a context manager, so that the file is closed
+    automatically when you're done with it.
+
+    ```python
+    with nd2.ND2File('some_file.nd2') as myfile:
+        print(myfile.metadata)
+        ...
+    ```
+
+The primary metadata is available as attributes on the file object:
+
+The key metadata outputs are:
+
+- [`ND2File.attributes`][nd2.ND2File.attributes]
+- [`ND2File.metadata`][nd2.ND2File.metadata] / [`ND2File.frame_metadata()`][nd2.ND2File.frame_metadata]
+- [`ND2File.experiment`][nd2.ND2File.experiment]
+- [`ND2File.text_info`][nd2.ND2File.text_info]
+- [`ND2File.events()`][nd2.ND2File.events]
+
+Other attributes of note include:
+
+| ATTRIBUTE          | EXAMPLE OUTPUT                           |
+|--------------------|------------------------------------------|
+| `myfile.shape`     | `(10, 2, 256, 256)`                      |
+| `myfile.ndim`      | `4`                                      |
+| `myfile.dtype`     | `np.dtype('uint16')`                     |
+| `myfile.size`      | `1310720` (total voxel elements)         |
+| `myfile.sizes`     | `{'T': 10, 'C': 2, 'Y': 256, 'X': 256}`  |
+| `myfile.voxel_size()` | `VoxelSize(x=0.65, y=0.65, z=1.0)`    |
+| `myfile.is_rgb`    | `False` (whether the file is rgb)        |
+
+### Binary masks and ROIs
+
+Binary masks, if present, can be accessed at
+[`ND2File.binary_data`][nd2.ND2File.binary_data].
+
+ROIs, if present, can be accessed at [`ND2File.rois`][nd2.ND2File.rois].
+
+### There's more in there!
+
+If you're still looking for something that you don't see in the above
+properties and methods, try looking through:
+
+- [ND2File.custom_data][nd2.ND2File.custom_data]
+- [ND2File.unstructured_metadata()][nd2.ND2File.unstructured_metadata]
+
+These methods parse and return more of the metadata found in the file,
+but no attempt is made to extract it into a more useful form.

docs/styles/extra.css

@@ -0,0 +1,68 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: 0.05rem solid var(--md-typeset-table-color);
+}
+
+.md-typeset .doc-heading code {
+  background-color: transparent;
+  display: inline-block;
+  max-width: 100%;
+  margin-left: 20px;
+  text-indent: -20px;
+}
+
+.md-typeset .doc-heading code span {
+  font-weight: 600;
+  color: rgb(166, 23, 25);
+}
+.md-typeset h3.doc-heading code span {
+  font-size: 0.8rem;
+}
+
+
+div.doc-function h2.doc-heading {
+  line-height: 1;
+  margin-left: 20px;
+  text-indent: -20px;
+  margin-bottom: 30px;
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: " ";
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: var(--md-typeset-a-color);
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
+
+article:has(> h1:first-child:nth-child(1)[id="nd2structures"]) .doc-label {
+  display: none;
+}
+
+article:has(> h1:first-child:nth-child(1)[id="nd2structures"]) h3 {
+  line-height: 1;
+  margin-top: 0;
+}
+
+
+.md-typeset__table {
+  min-width: 100%;
+}
+
+.md-typeset table:not([class]) {
+   display: table;
+}

mkdocs.yml

@@ -0,0 +1,71 @@
+site_name: nd2
+site_author: Talley Lambert
+repo_name: tlambert03/nd2
+repo_url: https://github.com/tlambert03/nd2
+edit_uri: edit/main/docs/
+site_description: A Python package for reading Nikon ND2 files
+copyright: 'Talley Lambert © 2021'
+strict: true
+
+watch:
+  - src
+
+theme:
+  name: material
+  icon:
+    logo: material/camera-iris
+    repo: fontawesome/brands/github
+  features:
+    - navigation.sections
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      primary: yellow
+      accent: teal
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: black
+      accent: yellow
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - tables
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_bases: false
+            show_source: false
+            show_root_toc_entry: false
+            docstring_style: numpy
+            docstring_section_style: list
+            show_signature_annotations: true
+            signature_crossrefs: true
+            filters:
+              - "!^__"
+              - "!^_"
+          import:
+            - https://numpy.org/doc/stable/objects.inv
+            - https://docs.python.org/3/objects.inv
+            - https://docs.xarray.dev/en/stable/objects.inv
+            - https://docs.dask.org/en/stable/objects.inv
+
+extra_css:
+  - styles/extra.css

pyproject.toml

@@ -52,6 +52,11 @@ dev = [
     "xarray",
     "lxml-stubs",
 ]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings-python",
+]
 
 [project.urls]
 homepage = "https://github.com/tlambert03/nd2"