docs(eyepy): add docstrings and cookbook examples

.github/workflows/ci.yaml

@@ -19,3 +19,25 @@ jobs:
     uses: MedVisBonn/eyepy/.github/workflows/_release.yaml@master
     secrets:
       PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+
+  deploy:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install \
+              mkdocs-material \
+              mkdocstrings = { version = "^0.19.0", extras = [ "python" ] } \
+              mkdocs-gen-files = "^0.4.0" \
+              mkdocs-literate-nav = "^0.5.0" \
+              mkdocs-section-index = "^0.3.5" \
+              pymdown-extensions = "^9.7"
+      - run: mkdocs gh-deploy --force

README.md

@@ -3,15 +3,10 @@
 [![PyPI version](https://badge.fury.io/py/eyepie.svg)](https://badge.fury.io/py/eyepie)
 [![DOI](https://zenodo.org/badge/292547201.svg)](https://zenodo.org/badge/latestdoi/292547201)
 
-
-This package is under active development and things might change without
-backwards compatibility. If you want to use eyepy in your project make sure to
-pin the version in your project requirements.
-
-
+Here you can find the [Documentation](https://www.MedVisBonn.github.io/eyepy)
 ## Features
 
-* Import HEYEY XML and VOL exports
+* Import HEYEY E2E, VOL and XML exports
 * Import B-Scans from a folder
 * Import public [AMD Dataset from Duke University](https://people.duke.edu/~sf59/RPEDC_Ophth_2013_dataset.htm)
 * Import data of the [RETOUCH Challenge](https://retouch.grand-challenge.org/).
@@ -34,10 +29,12 @@ import eyepy as ep
 ev = ep.data.load("drusen_patient")
 ```
 
-`eyepy` currently supports the HEYEX XML and VOL export format. Support for additional formats is easy to implement.
+`eyepy` currently supports the HEYEX E2E, XML and VOL export format. Support for additional formats is easy to implement.
 
 ```python
 import eyepy as ep
+# Import HEYEX VOL export
+ev = ep.import_heyex_e2e("path/to/file.e2e")
 # Import HEYEX XML export
 ev = ep.import_heyex_xml("path/to/folder")
 # Import HEYEX VOL export

docs/cookbook.md

@@ -1,11 +1,56 @@
 # Cookbook
 
+Here you learn how to use eyepy to perform common tasks.
+
 ## Import OCT data
 
+Currently `eyepy` supports the HEYEX E2E, VOL and XML formats, as well as reading data from several public OCT datasets. It is recommended to use one of the following functions to import OCT data into `eyepy`:
+
+``` python
+import eyepy as ep
+
+eye_volume = ep.import_bscan_folder("path/to/folder")
+eye_volume = ep.import_duke_mat("path/to/file.mat")
+eye_volume = ep.import_retouch("path/to/file.txt")
+eye_volume = ep.import_heyex_xml("path/to/file.xml")
+eye_volume = ep.import_heyex_vol("path/to/file.vol")
+eye_volume = ep.import_heyex_e2e("path/to/file.e2e", single=True)
+```
+
+All functions return a single `EyeVolume` object representing the data. E2E files may contain several oct volumes which you can retrieve by setting the parameter `single` to `False`:
+
+!!! Warning "Missing scale information"
+    For the E2E file the scale of both localizer axes as well as the B-scan x-axes has not been identified yet and is hardcoded. When importing B-scans from folders there is also no scale information available.
+
+
 ## Plot Localizer
 
+Most OCT volumes come with a localizer image. This image can be plotted using the `plot` method of the `EyeVolume` object:
+
+``` python
+eye_volume.plot()
+```
+
+There are several options to customize the plot:
+    + show B-scan positions or region (`bscan_positions` and `bscan_region` parameters)
+    + show enface projections or quantifications of OCT voxel annotaions such as drusen (`projections` and `quantifications` parameters)
+    + show only a specific region of the localizer image (`region` parameter)
+
+The plotting function is documented here: [EyeVolume.plot][eyepy.core.EyeVolume.plot]
+
+!!! Warning `region` parameter
+    The region parameter produces unexpected results in combination with `bscan_positions` and `bscan_region` parameters
 ## Plot Bscans
 
+B-scans can be plotted using the `plot` method of the `EyeBscan` object. You get `EyeBscan` objects by indexing the `EyeVolume` object or iterating over it. The following code plots the first B-scan of the volume together with the layer annotations for BM and RPE:
+
+``` python
+eye_volume[0].plot(layers=["BM", "RPE"])
+```
+
+The plotting function is documented here: [EyeBscan.plot][eyepy.core.EyeBscan.plot]
+
+<!---
 ## Access Meta data
 
 ## Modify Annotations
@@ -27,3 +72,4 @@
 ### Map between Localizer and OCT space
 
 ## Registration of Enface Images
+-->