[DOCS] add version dropdown and code block copy button

docs/_static/switcher.json

@@ -0,0 +1,12 @@
+[
+    {
+        "version": "dev",
+        "url": "https://wsinfer.readthedocs.io/en/latest/"
+    },
+    {
+        "name": "0.3.6 (stable)",
+        "version": "v0.3.6",
+        "url": "https://wsinfer.readthedocs.io/en/stable/",
+        "preferred": true
+    }
+]

docs/cli.rst

@@ -1,4 +1,4 @@
 .. click:: wsinfer.cli.cli:cli
    :prog: wsinfer
    :nested: full
-   :commands: list, run, togeojson, tosbu, patch
+   :commands: run, togeojson, tosbu, patch

docs/conf.py

@@ -6,7 +6,10 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "wsinfer"
+import os
+import wsinfer
+
+project = "WSInfer"
 copyright = "2023, Jakub Kaczmarzyk"
 author = "Jakub Kaczmarzyk"
 
@@ -16,10 +19,16 @@
 extensions = [
     "sphinx.ext.intersphinx",  # for links
     "sphinx.ext.napoleon",  # for google style docstrings
+    "sphinx.ext.viewcode",  # add links to code
     "autoapi.extension",  # to document the wsinfer api
     "sphinx_click",  # to document click command line
+    "sphinx_copybutton",  # add copy button to top-right of code blocks
 ]
 
+# Internationalization.
+language = "en"
+
+# AutoAPI options.
 autoapi_type = "python"
 autoapi_dirs = ["../wsinfer"]
 autoapi_options = [
@@ -43,7 +52,62 @@
     "openslide": ("https://openslide.org/api/python/", None),
 }
 
+# For editing the pages.
+html_context = {
+    "github_user": "SBU-BMI",
+    "github_repo": "wsinfer",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+# Define the json_url for our version switcher.
+json_url = "https://wsinfer.readthedocs.io/en/latest/_static/switcher.json"
+
+# Copied (with love) from conf.py of pydata-sphinx-theme.
+# Define the version we use for matching in the version switcher.
+version_match = os.environ.get("READTHEDOCS_VERSION")
+# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
+# If it is an integer, we're in a PR build and the version isn't correct.
+if not version_match or version_match.isdigit():
+    # For local development, infer the version to match from the package.
+    release = wsinfer.__version__
+    if "dev" in release or "rc" in release:
+        version_match = "dev"
+        # We want to keep the relative reference if we are in dev mode
+        # but we want the whole url if we are effectively in a released version
+        json_url = "_static/switcher.json"
+    else:
+        version_match = "v" + release
+
 html_theme = "pydata_sphinx_theme"
+# Many of these options are copied directly from pydata-sphinx-theme's conf.py.
+html_theme_options = {
+    "logo": {
+        "text": "WSInfer",
+        # "image_dark": "_static/logo-dark.svg",
+        # "alt_text": "WSInfer",
+    },
+    "use_edit_page_button": True,
+    "show_toc_level": 1,
+    "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
+    "navbar_center": ["version-switcher", "navbar-nav"],
+    "show_version_warning_banner": True,
+    # "show_nav_level": 2,
+    # "navbar_start": ["navbar-logo"],
+    # "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    # "navbar_persistent": ["search-button"],
+    # "primary_sidebar_end": ["custom-template.html", "sidebar-ethical-ads.html"],
+    # "article_footer_items": ["test.html", "test.html"],
+    # "content_footer_items": ["test.html", "test.html"],
+    # "footer_start": ["test.html", "test.html"],
+    # "secondary_sidebar_items": ["page-toc.html"],  # Remove the source buttons
+    "switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },
+}
+# html_logo = "_static/logo.svg"
+# html_favicon = "_static/log

docs/index.rst

@@ -42,19 +42,9 @@ To get help, report issues or request features, please
 repository. If you would like to make your patch classification model available in WSInfer, please
 get in touch with us! You can `submit a new GitHub issue <https://github.com/SBU-BMI/wsinfer/issues/new>`_.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   Installing <installing>
-   User Guide <user_guide>
-   CLI <cli>
-   QuPath Extension <qupath_ext>
-
-
-.. |img-tissue| image:: images/brca-tissue.png
+.. |img-tissue| image:: _static/brca-tissue.png
   :alt: TCGA BRCA sample slide
-.. |img-heatmap| image:: images/brca-heatmap.png
+.. |img-heatmap| image:: _static/brca-heatmap.png
   :alt: Heatmap of breast cancer detection
 
 +----------------+------------------------------+
@@ -63,6 +53,15 @@ get in touch with us! You can `submit a new GitHub issue <https://github.com/SBU
 | |img-tissue|   | |img-heatmap|                |
 +----------------+------------------------------+
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   Installing <installing>
+   User Guide <user_guide>
+   CLI <cli>
+   QuPath Extension <qupath_ext>
+
 .. _available-models:
 
 Available models

pyproject.toml

@@ -71,13 +71,14 @@ dev = [
     "types-Pillow",
     "types-PyYAML",
     "types-tqdm",
-    "Flake8-pyproject"
+    "Flake8-pyproject",
 ]
 docs = [
     "pydata-sphinx-theme",
     "sphinx<6.0.0",
     "sphinx-autoapi",
-    "sphinx-click"
+    "sphinx-click",
+    "sphinx-copybutton",
 ]
 openslide = [
     "openslide-python",