add client docs, hide unnecessary docs, add some styling (#468)

* add client docs, hide unnecessary docs, add some styling
* fix pylint ignore
* fix pylint ignore for real
* Update webknossos/webknossos/client/context.py

Co-authored-by: Philipp Otto <[email protected]>

Author: jstriebel

docs/mkdocs.yml

@@ -86,6 +86,9 @@ nav:
       - Graph: api/webknossos/skeleton/graph.md
       - Node: api/webknossos/skeleton/node.md
     - Annotation: api/webknossos/annotation/annotation.md
+    - Client:
+      - Overview: api/webknossos/client.md
+      - Authentication & Server Context: api/webknossos/client/context.md
 - wkcuber CLI: wkcuber/index.md
 
 plugins:

docs/overrides/css/lists.css

@@ -0,0 +1,13 @@
+/* Unordered list <ul> symbols:
+ * - level 1 is filled circle (default)
+ * - level 2 is hollow circle
+ * - level 3 is filled square
+ */
+ article ul ul {
+    list-style-type:  circle !important;
+    font-size: 0.95em;
+}
+
+article ul ul ul {
+    list-style-type:  square !important;
+}

docs/overrides/main.html

@@ -7,6 +7,7 @@
 	{{ super() }}
 	<link rel="stylesheet" href="{{ base_url }}/css/lightbox.min.css">
 	<link rel="stylesheet" href="{{ base_url }}/css/image_gallery.css">
+	<link rel="stylesheet" href="{{ base_url }}/css/lists.css">
 	<style type="text/css">
 		@font-face {
 			font-family: "Titillium Web";

docs/src/webknossos-py/examples/learned_segmenter.md

@@ -14,7 +14,7 @@
     _get_project_for_url_or_path,
 )
 
-from webknossos.client.context import get_generated_client
+from webknossos.client.context import _get_generated_client
 from webknossos.utils import snake_to_camel_case
 
 SCHEMA_URL = "https://converter.swagger.io/api/convert?url=https%3A%2F%2Fwebknossos.org%2Fswagger.json"
@@ -59,7 +59,7 @@ def add_api_prefix_for_non_data_paths(openapi_schema: Dict) -> None:
 
 
 def iterate_request_ids_with_responses() -> Iterable[Tuple[str, bytes]]:
-    from webknossos.client.generated.api.default import (
+    from webknossos.client._generated.api.default import (
         annotation_info,
         build_info,
         dataset_info,
@@ -68,7 +68,7 @@ def iterate_request_ids_with_responses() -> Iterable[Tuple[str, bytes]]:
 
     d = datetime.utcnow()
     unixtime = calendar.timegm(d.utctimetuple())
-    client = get_generated_client(enforce_auth=True)
+    client = _get_generated_client(enforce_auth=True)
 
     annotation_info_response = annotation_info.sync_detailed(
         typ="Explorational",

docs/src/webknossos-py/index.md

@@ -5,4 +5,4 @@ set -eEuo pipefail
 # This will maybe be fixed by https://github.com/PyCQA/pylint/issues/352
 # In the meantime, find all python files, except for the ./tests/.webknossos-server directory and lint them
 # Inspired by https://stackoverflow.com/questions/4210042/how-to-exclude-a-directory-in-find-command
-find . -type d \( -path ./webknossos/client/generated -o -path ./tests/.webknossos-server \) -prune -o -iname "*.py" -print | xargs poetry run python -m pylint -j4
+find . -type d \( -path ./webknossos/client/_generated -o -path ./tests/.webknossos-server \) -prune -o -iname "*.py" -print | xargs poetry run python -m pylint -j2

webknossos/__generate_client.py

@@ -64,7 +64,7 @@ disallow_untyped_defs = true
 no_implicit_optional = true
 
 [tool.pylint.MASTER]
-ignore=['generated']
+ignore=['webknossos/client/_generated']
 load-plugins=['_helpers.pylint_plugins.attrs_ng_api']
 
 [tool.pylint.'MESSAGES CONTROL']

webknossos/lint.sh

@@ -1,29 +1,29 @@
 import pytest
 
-from webknossos.client.context import get_generated_client
-from webknossos.client.defaults import DEFAULT_WEBKNOSSOS_URL
-from webknossos.client.generated.api.default import (
+from webknossos.client._defaults import DEFAULT_WEBKNOSSOS_URL
+from webknossos.client._generated.api.default import (
     annotation_info,
     build_info,
     dataset_info,
     datastore_list,
     health,
 )
-from webknossos.client.generated.client import Client
-from webknossos.client.generated.models.datastore_list_response_200_item import (
+from webknossos.client._generated.client import Client
+from webknossos.client._generated.models.datastore_list_response_200_item import (
     DatastoreListResponse200Item,
 )
+from webknossos.client.context import _get_generated_client
 from webknossos.utils import time_since_epoch_in_ms
 
 
 @pytest.fixture
 def client() -> Client:
-    return get_generated_client()
+    return _get_generated_client()
 
 
 @pytest.fixture
 def auth_client() -> Client:
-    return get_generated_client(enforce_auth=True)
+    return _get_generated_client(enforce_auth=True)
 
 
 # pylint: disable=redefined-outer-name

webknossos/pyproject.toml

@@ -8,7 +8,7 @@
 from attr import dataclass
 from boltons.cacheutils import cachedproperty
 
-from webknossos.client.context import get_context
+from webknossos.client.context import _get_context
 from webknossos.dataset import Dataset, Layer, SegmentationLayer
 from webknossos.skeleton import Skeleton, open_nml
 
@@ -95,11 +95,11 @@ def open_annotation(annotation_path: Union[str, PathLike]) -> "Annotation":
         ), "open_annotation() must be called with a path or an annotation url, e.g. https://webknossos.org/annotations/Explorational/6114d9410100009f0096c640"
         webknossos_url, annotation_type_str, annotation_id = match.groups()
         annotation_type = AnnotationType(annotation_type_str)
-        assert webknossos_url == get_context().url, (
-            f"The supplied url {webknossos_url} does not match your current context {get_context().url},\n"
+        assert webknossos_url == _get_context().url, (
+            f"The supplied url {webknossos_url} does not match your current context {_get_context().url},\n"
             + "please adapt it e.g. via 'with webknossos_context(…)'"
         )
-        from webknossos.client.download_annotation import download_annotation
+        from webknossos.client._download_annotation import download_annotation
 
         return download_annotation(annotation_type, annotation_id)