Doc: add docstring to (sub-) packages and modules

docs/api.rst

@@ -6,11 +6,13 @@
 API Documentation
 =================
 
+The class and package diagrams can be found at the `developer documentation<developer>`.
+
 :mod:`Siibra<siibra>`
 ====================
 
-Main Packages
-=============
+Main Packages and Modules
+=========================
 .. autopackagesummary:: siibra
    :toctree: _autosummary
 
@@ -24,23 +26,22 @@ Volumes
 .. autopackagesummary:: siibra.volumes
    :toctree: _autosummary
 
-Features
-========
-.. autopackagesummary:: siibra.features
-   :toctree: _autosummary
-
 Locations
 =========
 .. autopackagesummary:: siibra.locations
    :toctree: _autosummary
 
-Miscellaneous Helpers
-=====================
+Features
+========
+.. autopackagesummary:: siibra.features
+   :toctree: _autosummary
+
 Live queries
 ------------
 .. autopackagesummary:: siibra.livequeries
    :toctree: _autosummary
+
 Retrieval
----------
+=========
 .. autopackagesummary:: siibra.retrieval
    :toctree: _autosummary

siibra/features/__init__.py

@@ -12,7 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""Multimodal data features types and query mechanisms."""
 
 from . import (
     connectivity,

siibra/features/anchor.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Handles the relation between study targets and AtlasConcepts."""
 
 from ..commons import logger, Species
 
@@ -29,6 +30,7 @@
 
 AnatomicalAssignment = RelationAssignment[Union[Region, Location]]
 
+
 class AnatomicalAnchor:
     """
     Anatomical anchor to an atlas region,

siibra/features/connectivity/__init__.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Multimodal data features concerning connectivity data."""
 
 from .functional_connectivity import FunctionalConnectivity
 from .streamline_counts import StreamlineCounts

siibra/features/dataset/__init__.py

@@ -12,5 +12,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Non-preconfigured data features published as datasets."""
 
 from .ebrains import EbrainsDataFeature

siibra/features/dataset/ebrains.py

@@ -12,8 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
-# simple data features anchored to a point in space
+"""Non-preconfigured data features hosted at EBRAINS."""
 
 from zipfile import ZipFile
 from .. import anchor as _anchor

siibra/features/feature.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Handles multimodal data features and related queries."""
 
 from . import anchor as _anchor
 

siibra/features/image/image.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Multimodal data features in volume or image formats."""
 
 from zipfile import ZipFile
 from .. import feature

siibra/features/tabular/tabular.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Multimodal data features in tabular formats."""
 
 from zipfile import ZipFile
 from .. import feature

siibra/livequeries/__init__.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Feature queries requiring live query or on-the-fly calculations."""
 
 from .allen import AllenBrainAtlasQuery
 from .bigbrain import LayerwiseBigBrainIntensityQuery, BigBrainProfileQuery

siibra/livequeries/allen.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Query Allen Human Brain Atlas microarray data in specified volume."""
 
 from .query import LiveQuery
 

siibra/livequeries/bigbrain.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Matches BigBrain intesity profiles extracted by Wagstyl et al. to volumes."""
 
 from . import query
 

siibra/livequeries/ebrains.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Query data features published as Ebrains datasets with AtlasConcepts"""
 
 from ..features.dataset import ebrains as _ebrains
 from . import query

siibra/livequeries/query.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Handles feature queries that rely on live or on-the-fly calculations."""
 
 from ..commons import logger
 from ..features.feature import Feature

siibra/locations/__init__.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Handles spatial concepts and spatial operation like warping between spaces."""
 
 from .location import WholeBrain
 from .point import Point

siibra/locations/boundingbox.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""A box defined by two farthest corner coordinates on a specific space."""
 
 from . import point, pointset, location, boundingbox
 

siibra/locations/location.py

@@ -12,7 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""Concpets that have primarily spatial meaning."""
 
 import numpy as np
 from abc import ABC, abstractmethod

siibra/locations/point.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Singular coordinate defined on a space, possibly with an uncertainty."""
 
 from . import location, boundingbox, pointset
 from ..commons import logger

siibra/locations/pointset.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""A set of coordinates on a reference space."""
 
 from . import location, point, boundingbox
 

siibra/retrieval/__init__.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""File digestion and caching."""
 
 from .repositories import (
     GitlabConnector,

siibra/retrieval/cache.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Maintaining and hadnling caching files on disk."""
 
 import hashlib
 import os

siibra/retrieval/datasets.py

@@ -12,7 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""Metadata connection to EBRAINS datasets."""
 
 from .requests import MultiSourcedRequest, GitlabProxy, GitlabProxyEnum
 

siibra/retrieval/exceptions/__init__.py

@@ -1,3 +1,19 @@
+# Copyright 2018-2021
+# Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Exceptions concerning file retrieval processes."""
+
 class NoSiibraConfigMirrorsAvailableException(Exception):
     pass
 

siibra/retrieval/repositories.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Connect to repositories to browse and pull files within."""
 
 from .requests import (
     HttpRequest,

siibra/retrieval/requests.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Request files with decoders, lazy loading, and caching."""
 
 from .cache import CACHE
 from .exceptions import EbrainsAuthenticationError

siibra/vocabularies/__init__.py

@@ -12,7 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+"""Abbreviations and aliases."""
 
 from ..commons import InstanceTable
 

siibra/volumes/gifti.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Handles reading and preparing gii files."""
 
 from . import volume
 

siibra/volumes/neuroglancer.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Handles reading and preparing neuroglancer files."""
 
 from . import volume
 

siibra/volumes/nifti.py

@@ -12,6 +12,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Handles reading and preparing nifti files."""
 
 from . import volume