DOC Add versions and use pydata theme (#173)

doc/_static/version_switcher.json

@@ -0,0 +1,16 @@
+[
+    {
+        "name": "dev",
+        "version": "0.11.0.dev0",
+        "url": "https://jni.github.io/skan/dev"
+    },
+    {
+        "name": "0.10.x (stable)",
+        "version": "0.10.x",
+        "url": "https://jni.github.io/skan/stable"
+    },
+    {
+        "version": "0.9.x",
+        "url": "https://jni.github.io/skan/0.9.x"
+    }
+]

doc/conf.py

@@ -19,6 +19,7 @@
 # Add the local code to the Python path, so docs are generated for
 # current working copy
 import os
+import re
 import sys
 
 rundir = os.path.dirname(__file__)
@@ -104,20 +105,33 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = 'sphinx_material'
+html_theme = 'pydata_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 
-html_theme = 'sphinx_material'
+# Version match must match the 'version' key in version_swticher.json
+pattern = re.compile(r'^[0-9]+\.[0-9]+')
+version_match = pattern.search(version)
+if version_match:
+    version_match = version_match.group() + ".x"
+elif 'dev' in version:
+    version_match = "dev"
+else:
+    version_match = version
 
 # Material theme options (see theme.conf for more information)
 html_theme_options = {
     # Set the name of the project to appear in the navigation.
     'nav_title': 'Skan 🦴📏',
-
+    # pydata theme version switcher config
+    'navbar_end': ['version-switcher', 'navbar-icon-links'],
+    'switcher': {
+        'json_url': 'https://jni.github.io/skan/dev/_static/version_switcher.json',
+        'version_match': version_match,
+    },
     # Set you GA account ID to enable tracking
     # 'google_analytics_account': 'UA-XXXXX',
 
@@ -133,28 +147,13 @@
     'repo_url': 'https://github.com/jni/skan/',
     'repo_name': 'Skan',
 
-    # Visible levels of the global TOC; -1 means unlimited
-    'globaltoc_depth': 1,
-    # If False, expand all TOC entries
-    'globaltoc_collapse': False,
-    # If True, show hidden TOC entries
-    'globaltoc_includehidden': False,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
-}
-
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.

doc/examples/index.rst

@@ -0,0 +1,13 @@
+========
+Examples
+========
+
+skan examples.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   complete_analysis
+   sholl_analysis
+   visualizing_3d_skeletons

doc/sholl_analysis.md → doc/examples/sholl_analysis.md

@@ -26,7 +26,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 import zarr
 
-neuron = np.asarray(zarr.open('example-data/neuron.zarr.zip'))
+neuron = np.asarray(zarr.open('../example-data/neuron.zarr.zip'))
 
 fig, ax = plt.subplots()
 ax.imshow(neuron, cmap='gray')

doc/getting_started.md → doc/getting_started/getting_started.md

@@ -25,7 +25,7 @@ First, we load the images. These images were produced by an FEI scanning electro
 from glob import glob
 import imageio as iio
 
-files = glob('example-data/*.tif')
+files = glob('../example-data/*.tif')
 image0 = iio.imread(files[0], format='fei')
 ```
 

doc/getting_started/index.rst

@@ -0,0 +1,12 @@
+===============
+Getting started
+===============
+
+Getting started with skan.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   install
+   getting_started

doc/index.rst

@@ -9,18 +9,13 @@ Skeleton analysis with Skan 🦴📏
 Skan is a pure Python library to analyse skeleton images.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
 
-   install
-   getting_started
-   gui
-   complete_analysis
-   visualizing_3d_skeletons
-   sholl_analysis
-   faq
-   citing
+   getting_started/index
+   examples/index
    api/api
-   release-notes/index
+   gui
+   Miscellaneous <misc/index>
 
 
 Indices and tables

doc/misc/index.rst

@@ -0,0 +1,12 @@
+=============
+Miscellaneous
+=============
+
+FAQ, release notes and how to cite skan.
+
+.. toctree::
+   :maxdepth: 3
+
+   faq
+   release-notes/index
+   citing

requirements/doc.txt

@@ -5,5 +5,5 @@ tqdm>=4.11
 nb2plots>=0.5
 sphinxcontrib-bibtex
 sphinx<2
-sphinx_rtd_theme
+pydata-sphinx-theme>=0.8.1
 seaborn>=0.9

setup.cfg

@@ -87,3 +87,4 @@ docs =
     sphinxcontrib-bibtex
     myst-nb
     zarr
+    pydata-sphinx-theme>=0.8.1