Publish docs for webknossos and wkcuber (#403)

normanrz · web-flow · commit ba997ea646e5 · 2021-09-01T15:13:51.000+02:00
* publish both docs to s3

* rewrite docs links

* ci

* ci

* ci

* ci

* ci

* ci
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -106,32 +106,6 @@ jobs:
     - name: CLI tests
       run: tests/scripts/all_tests.sh
 
-    - name: Generate Docs
-      if: matrix.python-version == '3.8'
-      run: |
-        docs/api.sh --persist
-
-    - name: Push docs (for branch)
-      if: startsWith(github.event.ref, 'refs/heads') && matrix.python-version == '3.8'
-      env:
-        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-        AWS_DEFAULT_REGION: "eu-west-1"
-      run: |
-        CI_BRANCH=${GITHUB_REF##*/}
-        NORMALIZED_CI_BRANCH=${CI_BRANCH//[\/-]/_}
-        aws s3 sync --acl public-read docs/api s3://static.webknossos.org/lib-docs/${NORMALIZED_CI_BRANCH}
-
-    - name: Push docs (for tag)
-      if: startsWith(github.event.ref, 'refs/tags') && matrix.python-version == '3.8'
-      env:
-        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-        AWS_DEFAULT_REGION: "eu-west-1"
-      run: |
-        CI_TAG=$(git describe --tags)
-        aws s3 sync --acl public-read docs/api s3://static.webknossos.org/lib-docs/${CI_TAG}
-
     - name: Check if git is dirty
       run: |
         git diff --no-ext-diff --quiet --exit-code
@@ -265,6 +239,58 @@ jobs:
           docker push scalableminds/webknossos-cuber:latest
         fi
 
+  docs:
+    needs: [webknossos_linux, wkcuber_linux, wkcuber_win, wkcuber_mac]
+    runs-on: ubuntu-latest
+    if: |
+      always() &&
+      !contains(needs.*.result, 'failure') &&
+      !contains(needs.*.result, 'cancelled')
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.8
+        architecture: 'x64'
+
+    - name: Install dependencies
+      run: |
+        pip3 install -r requirements.txt
+        pushd webknossos
+          poetry install
+        popd
+        pushd wkcuber
+          poetry install
+        popd
+
+    - name: Build Docs
+      run: |
+        docs/api.sh --persist
+
+    - name: Push docs (for branch)
+      if: startsWith(github.event.ref, 'refs/heads')
+      env:
+        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        AWS_DEFAULT_REGION: "eu-west-1"
+      run: |
+        CI_BRANCH=${GITHUB_REF##*/}
+        NORMALIZED_CI_BRANCH=${CI_BRANCH//[\/-]/_}
+        aws s3 sync --acl public-read docs/api s3://static.webknossos.org/lib-docs/${NORMALIZED_CI_BRANCH}
+
+    - name: Push docs (for tag)
+      if: startsWith(github.event.ref, 'refs/tags')
+      env:
+        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        AWS_DEFAULT_REGION: "eu-west-1"
+      run: |
+        CI_TAG=$(git describe --tags)
+        aws s3 sync --acl public-read docs/api s3://static.webknossos.org/lib-docs/${CI_TAG}
+
+
   pypi:
     needs: [webknossos_linux, wkcuber_linux, wkcuber_win, wkcuber_mac]
     if: |
@@ -292,7 +318,7 @@ jobs:
       run: ./publish.sh
 
   success:
-    needs: [webknossos_linux, wkcuber_linux, wkcuber_win, wkcuber_mac, wkcuber_docker]
+    needs: [webknossos_linux, wkcuber_linux, wkcuber_win, wkcuber_mac, wkcuber_docker, docs]
     if: |
       always() &&
       !contains(needs.*.result, 'failure') &&
diff --git a/docs/api.sh b/docs/api.sh
@@ -6,7 +6,7 @@ PROJECT_DIR="$(dirname "$(dirname "$0")")"
 cd "$PROJECT_DIR/."
 
 if [ $# -eq 1 ] && [ "$1" = "--persist" ]; then
-    pdoc ./wkcuber  -o docs/api
+    pdoc ./webknossos/webknossos ./wkcuber/wkcuber -o docs/api
 else
-    pdoc ./wkcuber  -p 8095 -h 0.0.0.0
+    pdoc ./webknossos/webknossos ./wkcuber/wkcuber -p 8095 -h 0.0.0.0
 fi
diff --git a/requirements.txt b/requirements.txt
@@ -1,2 +1,3 @@
 dunamai==1.6.0
 poetry==1.1.8
+pdoc==7.4.0
diff --git a/webknossos/webknossos/__init__.py b/webknossos/webknossos/__init__.py
@@ -0,0 +1,6 @@
+"""
+# webknossos
+
+This module providess methods to modify or interact with webKnossos resources.
+Check out `webknossos.dataset` for detailed API documentation.
+"""
diff --git a/webknossos/webknossos/dataset/__init__.py b/webknossos/webknossos/dataset/__init__.py
@@ -3,15 +3,15 @@
 
 The high-level dataset API automatically reads and writes meta information for any dataset and updates them if necessary, such as the `datasource-properties.json`.
 
-A dataset (`wkcuber.api.dataset.Dataset`) is the entry-point for this API.
+A dataset (`webknossos.dataset.dataset.Dataset`) is the entry-point for this API.
 The dataset stores the data on disk in `.wkw`-files (see [webknossos-wrap (wkw)](https://github.com/scalableminds/webknossos-wrap)).
 
-Each dataset consists of one or more layers (wkcuber.api.layer.Layer), which themselves can comprise multiple magnifications (wkcuber.api.mag_view.MagView).
+Each dataset consists of one or more layers (webknossos.dataset.layer.Layer), which themselves can comprise multiple magnifications (webknossos.dataset.mag_view.MagView).
 
 ## Examples
 ### Opening Datasets
 ```python
-from wkcuber.api import Dataset
+from webknossos.dataset import Dataset
 
 dataset = Dataset(<path_to_dataset>)
 # Assuming that the dataset has a layer called 'color' and the layer has the magnification "1"
@@ -21,8 +21,8 @@
 
 ### Creating Datasets
 ```python
-from wkcuber.api import Dataset
-from wkcuber.api import Layer
+from webknossos.dataset import Dataset
+from webknossos.dataset import Layer
 
 dataset = Dataset.create(<path_to_new_dataset>, scale=(1, 1, 1))
 layer = dataset.add_layer(
@@ -37,7 +37,7 @@
 
 ### Reading Datasets
 ```python
-from wkcuber.api import Dataset
+from webknossos.dataset import Dataset
 
 dataset = Dataset(<path_to_dataset>)
 # Assuming that the dataset has a layer called 'color' and the layer has the magnification "1" and "2"
@@ -54,7 +54,7 @@
 
 ### Writing Datasets
 ```python
-from wkcuber.api import Dataset
+from webknossos.dataset import Dataset
 
 dataset = Dataset(<path_to_dataset>)
 # Assuming that the dataset has a layer called 'color' and the layer has the magnification "1" and "2"
diff --git a/webknossos/webknossos/dataset/dataset.py b/webknossos/webknossos/dataset/dataset.py
@@ -58,7 +58,7 @@ class Dataset:
 
     ### Creating Datasets
     ```python
-    from wkcuber.api.dataset import Dataset
+    from webknossos.dataset.dataset import Dataset
 
     dataset = Dataset.create(<path_to_new_dataset>, scale=(1, 1, 1))
     # Adds a new layer
@@ -74,7 +74,7 @@ class Dataset:
 
     ### Opening Datasets
     ```python
-    from wkcuber.api.dataset import Dataset
+    from webknossos.dataset.dataset import Dataset
 
     dataset = Dataset(<path_to_dataset>)
     # Assuming that the dataset has a layer called 'color'
@@ -83,7 +83,7 @@ class Dataset:
 
     ### Copying Datasets
     ```python
-    from wkcuber.api.dataset import Dataset
+    from webknossos.dataset.dataset import Dataset
 
     dataset = Dataset(<path_to_dataset>)
     # Copying the dataset with different block_len and file_len
@@ -149,7 +149,7 @@ def layers(self) -> Dict[str, Layer]:
 
     def get_layer(self, layer_name: str) -> Layer:
         """
-        Returns the layer called `layer_name` of this dataset. The return type is `wkcuber.api.layer.Layer`.
+        Returns the layer called `layer_name` of this dataset. The return type is `webknossos.dataset.layer.Layer`.
 
         This function raises an `IndexError` if the specified `layer_name` does not exist.
         """
@@ -177,7 +177,7 @@ def add_layer(
 
         Creates the folder `layer_name` in the directory of `self.path`.
 
-        The return type is `wkcuber.api.layer.Layer`.
+        The return type is `webknossos.dataset.layer.Layer`.
 
         This function raises an `IndexError` if the specified `layer_name` already exists.
         """
diff --git a/webknossos/webknossos/dataset/layer.py b/webknossos/webknossos/dataset/layer.py
@@ -140,13 +140,13 @@ def _element_class_to_dtype_per_channel(
 
 class Layer:
     """
-    A `Layer` consists of multiple `wkcuber.api.mag_view.MagView`s, which store the same data in different magnifications.
+    A `Layer` consists of multiple `webknossos.dataset.mag_view.MagView`s, which store the same data in different magnifications.
 
     ## Examples
 
     ### Adding layer to dataset
     ```python
-    from wkcuber.api.dataset import Dataset
+    from webknossos.dataset.dataset import Dataset
 
     dataset = Dataset(<path_to_dataset>)
     # Adds a new layer
@@ -158,7 +158,7 @@ class Layer:
 
     def __init__(self, dataset: "Dataset", properties: LayerProperties) -> None:
         """
-        Do not use this constructor manually. Instead use `wkcuber.api.layer.Dataset.add_layer()` to create a `Layer`.
+        Do not use this constructor manually. Instead use `webknossos.dataset.layer.Dataset.add_layer()` to create a `Layer`.
         """
         # It is possible that the properties on disk do not contain the number of channels.
         # Therefore, the parameter is optional. However at this point, 'num_channels' was already inferred.
@@ -258,7 +258,7 @@ def mags(self) -> Dict[Mag, MagView]:
 
     def get_mag(self, mag: Union[int, str, list, tuple, np.ndarray, Mag]) -> MagView:
         """
-        Returns the MagDataset called `mag` of this layer. The return type is `wkcuber.api.MagDataset`.
+        Returns the `MagView` called `mag` of this layer. The return type is `webknossos.dataset.mag_view.MagView`.
 
         This function raises an `IndexError` if the specified `mag` does not exist.
         """
@@ -284,7 +284,7 @@ def add_mag(
         diminished performance, as full blocks will automatically be read to pad the write actions. Alternatively,
         you can call mag.compress() after all the data was written
 
-        The return type is `wkcuber.api.mag_view.MagView`.
+        The return type is `webknossos.dataset.mag_view.MagView`.
 
         Raises an IndexError if the specified `mag` already exists.
         """
@@ -348,7 +348,7 @@ def get_or_add_mag(
 
     def delete_mag(self, mag: Union[int, str, list, tuple, np.ndarray, Mag]) -> None:
         """
-        Deletes the MagDataset from the `datasource-properties.json` and the data from disk.
+        Deletes the MagView from the `datasource-properties.json` and the data from disk.
 
         This function raises an `IndexError` if the specified `mag` does not exist.
         """
@@ -499,7 +499,7 @@ def downsample(
 
         Example:
         ```python
-        from wkcuber.downsampling_utils import SamplingModes
+        from webknossos.dataset.downsampling_utils import SamplingModes
 
         # ...
         # let 'layer' be a `Layer` with only `Mag(1)`
@@ -858,7 +858,7 @@ class LayerCategories:
     There are two different types of layers.
     This class can be used to specify the type of a layer during creation:
     ```python
-    from wkcuber.api.dataset import Dataset
+    from webknossos.dataset.dataset import Dataset
 
     dataset = Dataset(<path_to_dataset>)
     # Adds a new layer
diff --git a/webknossos/webknossos/dataset/mag_view.py b/webknossos/webknossos/dataset/mag_view.py
@@ -44,14 +44,14 @@ def _convert_mag1_offset(
 
 class MagView(View):
     """
-    A `MagView` contains all information about the data of a single magnification of a `wkcuber.api.layer.Layer`.
-    `MagView` inherits from `wkcuber.api.view.View`.
+    A `MagView` contains all information about the data of a single magnification of a `webknossos.dataset.layer.Layer`.
+    `MagView` inherits from `webknossos.dataset.view.View`.
     Therefore, the main difference between them is that a `MagView` handles the whole magnification,
     whereas the `View` only handles a sub-region.
 
     A `MagView` can read/write outside the specified bounding box (unlike a normal `View`).
     If necessary, the properties are automatically updated (e.g. if the bounding box changed).
-    This is possible because a `MagView` does have a reference to the `wkcuber.api.layer.Layer`.
+    This is possible because a `MagView` does have a reference to the `webknossos.dataset.layer.Layer`.
 
     The `global_offset` of a `MagView` is always `(0, 0, 0)` and its `size` is chosen so that the bounding box from the properties is fully inside this View.
     """
@@ -66,7 +66,7 @@ def __init__(
         create: bool = False,
     ) -> None:
         """
-        Do not use this constructor manually. Instead use `wkcuber.api.layer.Layer.add_mag()` to create a `MagView`.
+        Do not use this constructor manually. Instead use `webknossos.dataset.layer.Layer.add_mag()` to create a `MagView`.
         """
         header = wkw.Header(
             voxel_type=layer.dtype_per_channel,
@@ -122,7 +122,7 @@ def mag(self) -> Mag:
 
     def write(self, data: np.ndarray, offset: Vec3 = (0, 0, 0)) -> None:
         """
-        Writes the `data` at the specified `offset` to disk (like `wkcuber.api.view.View.write()`).
+        Writes the `data` at the specified `offset` to disk (like `webknossos.dataset.view.View.write()`).
 
         The `offset` refers to the absolute position, regardless of the offset in the properties (because the global_offset is set to (0, 0, 0)).
         If the data exceeds the original bounding box, the properties are updated.
diff --git a/webknossos/webknossos/dataset/view.py b/webknossos/webknossos/dataset/view.py
@@ -20,7 +20,7 @@ class View:
     A `View` is essentially a bounding box to a region of a specific `wkw.Dataset` that also provides functionality.
     Read- and write-operations are restricted to the bounding box.
     `View`s are designed to be easily passed around as parameters.
-    A `View`, in its most basic form, does not have a reference to the `wkcuber.api.dataset.Dataset`.
+    A `View`, in its most basic form, does not have a reference to the `webknossos.dataset.dataset.Dataset`.
     """
 
     def __init__(
@@ -34,7 +34,7 @@ def __init__(
         mag_view_bbox_at_creation: Optional[BoundingBox] = None,
     ):
         """
-        Do not use this constructor manually. Instead use `wkcuber.api.mag_view.MagView.get_view()` to get a `View`.
+        Do not use this constructor manually. Instead use `webknossos.dataset.mag_view.MagView.get_view()` to get a `View`.
         """
         self._dataset: Optional[Dataset] = None
         self._path = path_to_mag_view
@@ -310,7 +310,7 @@ def for_each_chunk(
 
         Example:
         ```python
-        from wkcuber.utils import get_executor_for_args, named_partial
+        from webknossos.utils import get_executor_for_args, named_partial
 
         def some_work(args: Tuple[View, int], some_parameter: int) -> None:
             view_of_single_chunk, i = args
diff --git a/wkcuber/poetry.lock b/wkcuber/poetry.lock
diff --git a/wkcuber/pyproject.toml b/wkcuber/pyproject.toml
diff --git a/wkcuber/wkcuber/__init__.py b/wkcuber/wkcuber/__init__.py
diff --git a/wkcuber/wkcuber/api/__init__.py b/wkcuber/wkcuber/api/__init__.py

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`dunamai==1.6.0`
`2`	`2`	`poetry==1.1.8`
	`3`	`+pdoc==7.4.0`