Add a Jupyter notebook example

.circleci/config.yml

@@ -201,6 +201,9 @@ jobs:
     executor: toxandnode
     steps:
       - checkout
+      - run:
+          name: Install dependencies
+          command: apt-get update -yq && apt-get install -yq pandoc && pandoc --version
       - tox:
           env: docs,lint,lintclient
       - store_artifacts:

.gitignore

@@ -73,4 +73,5 @@ docs/source/*
 .pre-commit-config.yaml
 
 *.ipynb
+!docs/*.ipynb
 NOTES.md

docs/conf.py

@@ -42,6 +42,8 @@
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinxcontrib.jquery',
+    'IPython.sphinxext.ipython_console_highlighting',
+    'nbsphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -50,7 +52,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['_build/**.ipynb', '**.ipynb_checkpoints']
 
 
 # -- Options for HTML output -------------------------------------------------

docs/index.rst

@@ -41,6 +41,7 @@
    _build/girder_large_image_annotation/modules
    girder_annotation_config_options
    annotations
+   notebooks
    development
 
 

docs/notebooks.rst

@@ -0,0 +1,10 @@
+=========================
+Jupyter Notebook Examples
+=========================
+
+large_image is often used inside Jupyter notebooks.
+
+.. toctree::
+   :maxdepth: 1
+
+   ./large_image_examples.ipynb

large_image/cache_util/cachefactory.py

@@ -117,7 +117,7 @@ def getFirstAvailableCache():
         except TileCacheError:
             continue
     if cache is not None:
-        config.getConfig('logprint').info(
+        config.getConfig('logprint').debug(
             f'Automatically setting `{cacheBackend}` as cache_backend from availableCaches',
         )
         config.setConfig('cache_backend', cacheBackend)
@@ -169,7 +169,7 @@ def getCache(self, numItems=None, cacheName=None, inProcess=False):
             cacheLock = threading.Lock()
 
         if not inProcess and not CacheFactory.logged:
-            config.getConfig('logprint').info(f'Using {cacheBackend} for large_image caching')
+            config.getConfig('logprint').debug(f'Using {cacheBackend} for large_image caching')
             CacheFactory.logged = True
 
         return cache, cacheLock

ruff.toml

@@ -1,6 +1,6 @@
+include = ["*.py", "*.pyi", "**/pyproject.toml", "*.ipynb"]
 exclude = [
     "build",
-    "docs",
     "*/web_client/*",
     "*/*egg*/*",
 ]
@@ -56,6 +56,12 @@ select = [
     "RSE",
 ]
 
+[per-file-ignores]
+# allow "useless expressions" as it shows output
+# allow non-top level imports
+# allow long lines
+"docs/large_image_examples.ipynb" = ["B018", "E402", "E501"]
+
 [flake8-quotes]
 inline-quotes = "single"
 

tox.ini

@@ -208,6 +208,9 @@ commands = {[testenv:dev]commands}
 description = Build documentation
 deps =
   -rrequirements-test.txt
+  jupyter
+  nbsphinx
+  pypandoc
   sphinx
   sphinx-rtd-theme
   sphinxcontrib-jquery