Updates to readme & docs (#451)

* updated README wip
* updated readmes
* spell check
* update to reamde
* update readme on metadata
* Update README.md
* Update README.md
* Merge remote-tracking branch 'origin/master' into readme2
* improve docs, move dataset examples into example folder, add more api reference links
* Merge remote-tracking branch 'origin/master' into readme2
* fix import
* add missing init
* use import webknossos as wk in examples
* add examples and annotation API from client PR to docs
* Merge remote-tracking branch 'origin/master' into readme2
* update requirements
* Merge branch 'master' into readme2
* Update docs/src/webknossos-py/examples/learned_segmenter.md

Co-authored-by: Philipp Otto <[email protected]>
* Apply suggestions from code review

Co-authored-by: Philipp Otto <[email protected]>
* PR feedback
* guard against errors in pdoc leading to missing api docs

Author: hotzenklotz

.gitignore

@@ -1 +1,119 @@
+*.sublime-project
+*.sublime-workspace
+.vagrant
+.history
+wk_data
+
 .idea
+*.iml
+.vscode
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+wheels/
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+test_coverage_html/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+*.cover
+.pytest_cache/
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+.history
+
+/.cfut
+/models
+.hash
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.DS_Store
+.docker_credentials
+*.simg
+slurm-*.out

README.md

@@ -1,10 +1,27 @@
 # webKnossos-libs
+[![PyPI version](https://img.shields.io/pypi/v/webknossos)](https://pypi.python.org/pypi/webknossos)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/webknossos.svg)](https://pypi.python.org/pypi/webknossos)
+[![Build Status](https://img.shields.io/github/workflow/status/scalableminds/webknossos-libs/CI/master)](https://github.com/scalableminds/webknossos-libs/actions?query=workflow%3A%22CI%22)
+[![Documentation](https://img.shields.io/badge/docs-passing-brightgreen.svg)](https://docs.webknossos.org/webknossos-py/index.html)
+[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
 <img align="right" src="https://static.webknossos.org/images/oxalis.svg" alt="webKnossos Logo" />
 
 ## [webKnossos Python API](webknossos)
-Python API to work with webKnossos datasets, annotations and for webKnossos server interaction.
+Python API for working with [webKnossos](https://webknossos.org) datasets, annotations, and for webKnossos server interaction.
+
+Use this for:
+- reading/writing/manipulating raw 2D/3D image data and volume annotations/segmentation in webKnossos wrap (*.wkw) format
+- handling/manipulation of webKnossos datasets
+- reading/writing/manipulating webKnossos skeleton annotations (*.nml)
+- up- & downloading annotations and datasets from your webKnossos instance
+- executing any of the wkcuber operations from below from your code
 
-Currently under construction :construction:
 
 ## [webKnossos cuber (wkcuber) CLI](wkcuber)
-CLI tool to creating and manipulate [webKnossos](https://webknossos.org) [WKW](https://github.com/scalableminds/webknossos-wrap) datasets. WKW is a container format for efficiently storing large-scale 3D images as found in microscopy data.
+CLI tool for creating and manipulating [webKnossos](https://webknossos.org) [WKW](https://github.com/scalableminds/webknossos-wrap) datasets. WKW is a container format for efficiently storing large-scale 3D images as found in microscopy data.
+
+Use this for:
+- converting Tiff-stacks and other data formats for volume image data to webKnossos-compatible *.wkw files from the CLI
+- up/downsampling of *.wkw files to different magnification levels (image pyramid) from the CLI
+- compressing your *.wkw files to save disk space from the CLI

docs/generate.sh

@@ -22,6 +22,19 @@ else
     poetry run pdoc ../webknossos/webknossos ../wkcuber/wkcuber -t pdoc_templates -o src/api
     # rename .html files to .md
     find src/api -iname "*.html" -exec sh -c 'mv "$0" "${0%.html}.md"' {} \;
+    # assert that API docs are written
+    webknossos_files="$(find src/api/webknossos -type f -name "*.md" | wc -l)"
+    wkcuber_files="$(find src/api/wkcuber -type f -name "*.md" | wc -l)"
+    if ! [ "$webknossos_files" -gt "50" ]; then
+       echo "Error: There are too few ($webknossos_files, expected > 80) files in src/api/webknossos,"
+       echo "probably there was an error with pdoc before!"
+       exit 1
+    fi
+    if ! [ "$wkcuber_files" -gt "25" ]; then
+       echo "There are too few ($wkcuber_files, expected > 25) files in src/api/wkcuber,"
+       echo "probably there was an error with pdoc before!"
+       exit 1
+    fi
     if [ $# -eq 1 ] && [ "$1" = "--persist" ]; then
         PYTHONPATH=$PYTHONPATH:. poetry run mkdocs build
     else

docs/mkdocs.yml

@@ -29,14 +29,14 @@ theme:
   features:
     - navigation.instant
     - navigation.tabs
+    - navigation.tabs.sticky
     - navigation.sections
     - navigation.top
 
 nav:
 - webKnossos:
-  - Summary:
-    - webknossos/index.md
-    - webknossos/getting_started.md
+  - webknossos/index.md
+  - webknossos/getting_started.md
   - Guides:
     - webknossos/dashboard.md
     - webknossos/skeleton_annotation.md
@@ -63,8 +63,29 @@ nav:
     - Email Support: mailto:[email protected]
     - Commercial Support: https://scalableminds.com" target="_blank
 - Python Library:
-  - Intro: webknossos-py/index.md
-  - Dataset API: api/webknossos/dataset.md
+  - webknossos-py/index.md
+  - webknossos-py/installation.md
+  - Usage Examples:
+      - webknossos-py/examples/dataset_usage.md
+      - webknossos-py/examples/upload_image_data.md
+      - webknossos-py/examples/learned_segmenter.md
+      - webknossos-py/examples/skeleton_synapse_candidates.md
+  - API Reference:
+    - Geometry:
+      - BoundingBox: api/webknossos/geometry/bounding_box.md
+      - Mag: api/webknossos/geometry/mag.md
+      - Vec3Int: api/webknossos/geometry/vec3_int.md
+    - Dataset:
+      - Dataset: api/webknossos/dataset/dataset.md
+      - Layer: api/webknossos/dataset/layer.md
+      - MagView: api/webknossos/dataset/mag_view.md
+      - View: api/webknossos/dataset/view.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
 - wkcuber CLI: wkcuber/index.md
 
 plugins:
@@ -76,9 +97,16 @@ plugins:
 markdown_extensions:
 - admonition
 - attr_list
+- md_in_html
 - md_extensions.pdoc_toc_extension
 - md_extensions.video_embed_extension
 - md_extensions.mdlightbox
+- pymdownx.highlight
+- pymdownx.inlinehilite
+- pymdownx.superfences
+- pymdownx.snippets:
+    base_path: ".."
+    check_paths: true
 - pymdownx.emoji:
     emoji_index: !!python/name:materialx.emoji.twemoji
     emoji_generator: !!python/name:materialx.emoji.to_svg

docs/overrides/css/image_gallery.css

@@ -3,7 +3,7 @@
 
 /* 2 items */
 article a:first-child:nth-last-child(2) > img,
-article a:first-child:nth-last-child(2) ~ a > img{
+article a:first-child:nth-last-child(2) ~ a > img {
     max-width: calc(100%/2 - 1em);
 }
 
@@ -15,42 +15,52 @@ article a:first-child:nth-last-child(3) ~ a > img {
 
 /* 4 items */
 article a:first-child:nth-last-child(4) > img,
-article a:first-child:nth-last-child(4) ~ a > img{
+article a:first-child:nth-last-child(4) ~ a > img {
     max-width: calc(100%/4 - 1em);
 }
 
 /* 5 items */
 article a:first-child:nth-last-child(5) > img,
-article a:first-child:nth-last-child(5) ~ a > img{
+article a:first-child:nth-last-child(5) ~ a > img {
     max-width: calc(100%/5 - 1em);
 }
 
 /* 6 items */
 article a:first-child:nth-last-child(6) > img,
-article a:first-child:nth-last-child(6) ~ a > img{
+article a:first-child:nth-last-child(6) ~ a > img {
     max-width: calc(100%/6 - 1em);
 }
 
 /* 7 items */
 article a:first-child:nth-last-child(7) > img,
-article a:first-child:nth-last-child(7) ~ a > img{
+article a:first-child:nth-last-child(7) ~ a > img {
     max-width: calc(100%/7 - 1em);
 }
 
 /* 8 items */
 article a:first-child:nth-last-child(8) > img,
-article a:first-child:nth-last-child(8) ~ a > img{
+article a:first-child:nth-last-child(8) ~ a > img {
     max-width: calc(100%/8 - 1em);
 }
 
 /* 9 items */
 article a:first-child:nth-last-child(9) > img,
-article a:first-child:nth-last-child(9) ~ a > img{
+article a:first-child:nth-last-child(9) ~ a > img {
     max-width: calc(100%/9 - 1em);
 }
 
 /* 10 items */
 article a:first-child:nth-last-child(10) > img,
-article a:first-child:nth-last-child(10) ~ a > img{
+article a:first-child:nth-last-child(10) ~ a > img {
     max-width: calc(100%/10 - 1em);
 }
+
+/*************/
+/*  FIGURES  */
+/*************/
+
+/* Always set to 2 items */
+article figure {
+    max-width: calc(100%/2 - 1em) !important;
+    display: inline-grid !important;
+}

docs/pdoc_templates/frame.html.jinja2

@@ -4,11 +4,8 @@
 - id: {{ m.qualname }}
   name: class {{ m.qualname }}
   level: {{ level }}
-  children: {% if not m.own_members %}[]
-  {% else %}
-
+  children:
   {{ toc_members(m.own_members, level+1) | indent(2) }}
-  {% endif %}
     {% elif m.type == "module" %}
 - id: {{ m.name }}
   name: module {{ m.name }}
@@ -35,6 +32,7 @@
   level: {{ level }}
   children: []
     {% endif %}
+  {% else %}{% if level > 2 %}  []{% endif %}
   {% endfor %}
 {% enddefaultmacro %}
 ---