From 2d8f12c7c0c927fc7af4c994413ee07fa0c16949 Mon Sep 17 00:00:00 2001 From: Lucy Liu Date: Thu, 2 Jun 2022 17:28:43 +1000 Subject: [PATCH] DOC Add versions and use pydata theme (#173) --- doc/_static/version_switcher.json | 16 +++++++++ doc/conf.py | 35 +++++++++---------- doc/{ => examples}/complete_analysis.md | 0 doc/examples/index.rst | 13 +++++++ doc/{ => examples}/sholl_analysis.md | 2 +- .../visualizing_3d_skeletons.md | 0 doc/{ => getting_started}/getting_started.md | 2 +- doc/getting_started/index.rst | 12 +++++++ doc/{ => getting_started}/install.rst | 0 doc/index.rst | 15 +++----- doc/{ => misc}/citing.rst | 0 doc/{ => misc}/faq.md | 0 doc/misc/index.rst | 12 +++++++ doc/{ => misc}/release-notes/index.rst | 0 .../release-notes/release-latest.md | 0 .../release-notes/release-v0.10.0.md | 0 doc/{ => misc}/release-notes/release-v0.9.md | 0 requirements/doc.txt | 2 +- setup.cfg | 1 + 19 files changed, 79 insertions(+), 31 deletions(-) create mode 100644 doc/_static/version_switcher.json rename doc/{ => examples}/complete_analysis.md (100%) create mode 100644 doc/examples/index.rst rename doc/{ => examples}/sholl_analysis.md (97%) rename doc/{ => examples}/visualizing_3d_skeletons.md (100%) rename doc/{ => getting_started}/getting_started.md (99%) create mode 100644 doc/getting_started/index.rst rename doc/{ => getting_started}/install.rst (100%) rename doc/{ => misc}/citing.rst (100%) rename doc/{ => misc}/faq.md (100%) create mode 100644 doc/misc/index.rst rename doc/{ => misc}/release-notes/index.rst (100%) rename doc/{ => misc}/release-notes/release-latest.md (100%) rename doc/{ => misc}/release-notes/release-v0.10.0.md (100%) rename doc/{ => misc}/release-notes/release-v0.9.md (100%) diff --git a/doc/_static/version_switcher.json b/doc/_static/version_switcher.json new file mode 100644 index 00000000..58762262 --- /dev/null +++ b/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" + } +] diff --git a/doc/conf.py b/doc/conf.py index 357d4905..cfc0697a 100644 --- a/doc/conf.py +++ b/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,12 +147,6 @@ '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, @@ -146,15 +154,6 @@ # 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. diff --git a/doc/complete_analysis.md b/doc/examples/complete_analysis.md similarity index 100% rename from doc/complete_analysis.md rename to doc/examples/complete_analysis.md diff --git a/doc/examples/index.rst b/doc/examples/index.rst new file mode 100644 index 00000000..7a72a198 --- /dev/null +++ b/doc/examples/index.rst @@ -0,0 +1,13 @@ +======== +Examples +======== + +skan examples. + + +.. toctree:: + :maxdepth: 1 + + complete_analysis + sholl_analysis + visualizing_3d_skeletons diff --git a/doc/sholl_analysis.md b/doc/examples/sholl_analysis.md similarity index 97% rename from doc/sholl_analysis.md rename to doc/examples/sholl_analysis.md index 6e9aed1f..68a47ac2 100644 --- a/doc/sholl_analysis.md +++ b/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') diff --git a/doc/visualizing_3d_skeletons.md b/doc/examples/visualizing_3d_skeletons.md similarity index 100% rename from doc/visualizing_3d_skeletons.md rename to doc/examples/visualizing_3d_skeletons.md diff --git a/doc/getting_started.md b/doc/getting_started/getting_started.md similarity index 99% rename from doc/getting_started.md rename to doc/getting_started/getting_started.md index a03df85c..f35a378b 100644 --- a/doc/getting_started.md +++ b/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') ``` diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst new file mode 100644 index 00000000..9e627620 --- /dev/null +++ b/doc/getting_started/index.rst @@ -0,0 +1,12 @@ +=============== +Getting started +=============== + +Getting started with skan. + + +.. toctree:: + :maxdepth: 1 + + install + getting_started diff --git a/doc/install.rst b/doc/getting_started/install.rst similarity index 100% rename from doc/install.rst rename to doc/getting_started/install.rst diff --git a/doc/index.rst b/doc/index.rst index ef75ee1c..f8ee22c8 100644 --- a/doc/index.rst +++ b/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 Indices and tables diff --git a/doc/citing.rst b/doc/misc/citing.rst similarity index 100% rename from doc/citing.rst rename to doc/misc/citing.rst diff --git a/doc/faq.md b/doc/misc/faq.md similarity index 100% rename from doc/faq.md rename to doc/misc/faq.md diff --git a/doc/misc/index.rst b/doc/misc/index.rst new file mode 100644 index 00000000..8ce29c42 --- /dev/null +++ b/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 diff --git a/doc/release-notes/index.rst b/doc/misc/release-notes/index.rst similarity index 100% rename from doc/release-notes/index.rst rename to doc/misc/release-notes/index.rst diff --git a/doc/release-notes/release-latest.md b/doc/misc/release-notes/release-latest.md similarity index 100% rename from doc/release-notes/release-latest.md rename to doc/misc/release-notes/release-latest.md diff --git a/doc/release-notes/release-v0.10.0.md b/doc/misc/release-notes/release-v0.10.0.md similarity index 100% rename from doc/release-notes/release-v0.10.0.md rename to doc/misc/release-notes/release-v0.10.0.md diff --git a/doc/release-notes/release-v0.9.md b/doc/misc/release-notes/release-v0.9.md similarity index 100% rename from doc/release-notes/release-v0.9.md rename to doc/misc/release-notes/release-v0.9.md diff --git a/requirements/doc.txt b/requirements/doc.txt index e939ccf8..56a10c79 100644 --- a/requirements/doc.txt +++ b/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 diff --git a/setup.cfg b/setup.cfg index 4202cf5d..4a3cab44 100644 --- a/setup.cfg +++ b/setup.cfg @@ -87,3 +87,4 @@ docs = sphinxcontrib-bibtex myst-nb zarr + pydata-sphinx-theme>=0.8.1