wk-libs docs: restructure index & add stability policy (#634)

Author: jstriebel

docs/mkdocs.yml

@@ -70,13 +70,15 @@ nav:
   - webknossos-py/index.md
   - webknossos-py/installation.md
   - Usage Examples:
-      - webknossos-py/examples/dataset_usage.md
-      - webknossos-py/examples/upload_image_data.md
+      - Dataset Examples:
+        - webknossos-py/examples/dataset_usage.md
+        - webknossos-py/examples/upload_image_data.md
       - webknossos-py/examples/apply_merger_mode.md
       - webknossos-py/examples/learned_segmenter.md
       - webknossos-py/examples/skeleton_synapse_candidates.md
-      - webknossos-py/examples/user_times.md
-      - webknossos-py/examples/annotation_project_administration.md
+      - Administration Examples:
+        - webknossos-py/examples/user_times.md
+        - webknossos-py/examples/annotation_project_administration.md
   - API Reference:
     - Overview: api/webknossos.md
     - Geometry:
@@ -88,24 +90,26 @@ nav:
       - Layer: api/webknossos/dataset/layer.md
       - MagView: api/webknossos/dataset/mag_view.md
       - View: api/webknossos/dataset/view.md
+    - Annotation: api/webknossos/annotation/annotation.md
     - Skeleton:
       - Skeleton: api/webknossos/skeleton/skeleton.md
       - Group: api/webknossos/skeleton/group.md
       - Graph: api/webknossos/skeleton/graph.md
       - Node: api/webknossos/skeleton/node.md
-    - Annotation: api/webknossos/annotation/annotation.md
     - Authentication & Server Context: api/webknossos/client/context.md
     - Administration:
       - User: api/webknossos/administration/user.md
       - Project: api/webknossos/administration/project.md
       - Task: api/webknossos/administration/task.md
+  - Other:
     - webknossos-py/changelog.md
-  - Getting Help:
-    - webknossos-py/development.md
-    - Community Support: https://forum.image.sc/tag/webknossos" target="_blank
-    - Email Support: mailto:[email protected]
-    - Commercial Support: https://scalableminds.com" target="_blank
-  - GitHub: https://github.com/scalableminds/webknossos-libs/tree/master/webknossos" target="_blank
+    - webknossos-py/stability_policy.md
+    - Getting Help:
+      - webknossos-py/development.md
+      - Community Support: https://forum.image.sc/tag/webknossos" target="_blank
+      - Email Support: mailto:[email protected]
+      - Commercial Support: https://scalableminds.com" target="_blank
+    - GitHub: https://github.com/scalableminds/webknossos-libs/tree/master/webknossos" target="_blank
 - webKnossos Cuber:
   - wkcuber CLI: wkcuber/index.md
   - wkcuber/changelog.md
@@ -114,7 +118,6 @@ nav:
     - Email Support: mailto:[email protected]
     - Commercial Support: https://scalableminds.com" target="_blank
   - GitHub: https://github.com/scalableminds/webknossos-libs/tree/master/wkcuber" target="_blank
-  
 
 plugins:
 - search

docs/src/webknossos-py/stability_policy.md

@@ -0,0 +1,19 @@
+# Stability Policy
+
+This project adheres to [Semantic Versioning](http://semver.org/) regarding the Python API
+compatibility, using the `MAJOR.MINOR.PATCH` version number format.
+To allow fast development of the webKnossos server, the server-client interaction may need minor
+version upgrades to ensure full functionality. Starting from v1 and above, minor and patch upgrades won't require
+changes consuming the Python API as long as the following two points are followed:
+
+1. To ensure compatibility across minor and patch upgrades, please import everything directly
+   from the webknossos module, not from submodules, e.g. use
+   ```python
+   import webknossos as wk
+   wk.Skeleton()
+   # or
+   from webknossos import Dataset
+   Dataset()
+   ```
+2. Methods, functions, classes and variables prefixed with an underscore are not part of the public API
+   and may change anytime.

webknossos/Changelog.md

@@ -2,6 +2,9 @@
 
 All notable changes to the webknossos python library are documented in this file.
 
+Please see the [Stability Policy](./stability_policy.md) for details about the version schema
+and compatibility implications.
+
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/) `MAJOR.MINOR.PATCH`.
 For upgrade instructions, please check the respective *Breaking Changes* sections.