Merge pull request #763 from NeurodataWithoutBorders/docs_version_swi…

…tcher

Add docs version switcher, favicon

.github/workflows/chromatic.yml

@@ -6,7 +6,7 @@ on:
     types: [submitted]
 
 jobs:
-  test:
+  upload:
     if: github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request_review' && github.event.review.state == 'approved')
     runs-on: ubuntu-latest
     steps:

.readthedocs.yaml

@@ -6,9 +6,9 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.12"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+clean:
+	rm -rf "$(BUILDDIR)"
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/switcher.json

@@ -0,0 +1,12 @@
+[
+    {
+        "version": "dev",
+        "url": "https://nwb-guide.readthedocs.io/en/latest/"
+    },
+    {
+        "name": "0.0.15",
+        "version": "v0.0.15",
+        "url": "https://nwb-guide.readthedocs.io/en/v0.0.15/",
+        "preferred": true
+    }
+]

docs/conf.py

@@ -1,11 +1,15 @@
 import sys
 import inspect
 from pathlib import Path
+import json
+import os
 
-from conf_extlinks import extlinks, intersphinx_mapping
-
+sys.path.insert(0, str(Path(__file__).resolve().parents[0]))
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
+from conf_extlinks import extlinks, intersphinx_mapping  # noqa: E402, F401
+
+
 project = "NWB GUIDE"
 copyright = "2022, CatalystNeuro"  # TODO: how to include NWB?
 author = "Garrett Flynn, Cody Baker, Ryan Ly, Oliver Ruebel, and Ben Dichter"
@@ -16,27 +20,34 @@
     "sphinx.ext.intersphinx",  # Allows links to other sphinx project documentation sites
     "sphinx_search.extension",  # Allows for auto search function the documentation
     "sphinx.ext.viewcode",  # Shows source code in the documentation
-"sphinx.ext.extlinks",  # Allows to use shorter external links defined in the extlinks variable.
+    "sphinx.ext.extlinks",  # Allows to use shorter external links defined in the extlinks variable.
+    "sphinx_favicon",  # Allows to set a favicon for the documentation
 ]
 
 templates_path = ["_templates"]
 master_doc = "index"
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
 
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = 'img/favicon.ico'  # TODO
+html_show_sourcelink = False
 
-# These paths are either relative to html_static_path or fully qualified paths (eg. https://...)
-html_css_files = [
-    "css/custom.css",
+html_logo = "assets/logo-guide-draft-transparent-tight.png"
+
+# configure the favicon via the sphinx_favicon extension
+favicons = [
+    "favicon.ico",
+    "favicon-16x16.png",
+    "favicon-32x32.png",
+    "android-chrome-192x192.png",
+    "android-chrome-512x512.png",
+    "apple-touch-icon.png",
 ]
 
-html_theme_options = {
-    "collapse_navigation": False,
-}
+# These paths are either relative to html_static_path or fully qualified paths (eg. https://...)
+# html_css_files = [
+#     "css/custom.css",
+# ]
 
 linkcheck_anchors = False
 
@@ -66,6 +77,34 @@
 }
 add_module_names = False
 
+# Define the json_url for our version switcher.
+json_url = "https://nwb-guide.readthedocs.io/en/latest/_static/switcher.json"
+
+# Define the version we use for matching in the version switcher.
+# Adapted from https://github.com/pydata/pydata-sphinx-theme/blob/a4eaf774f97400d12d9cfc53b410122f1a8d88c6/docs/conf.py
+version_match = os.environ.get("READTHEDOCS_VERSION")
+with open("../package.json") as f:
+    release = json.load(f)["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 it's "latest" → change to "dev" (that's what we want the switcher to call it)
+if not version_match or version_match.isdigit() or version_match == "latest":
+    # For local development, infer the version to match from the package.
+    # NOTE: In local development, you can't just open the built HTML file and have the version switcher work
+    # Use `python -m http.server -d docs/build/html/` and open the page at http://localhost:8000
+    # In local development, the version switcher will always show "dev" and use the local switcher.json
+    version_match = "dev"
+    json_url = "_static/switcher.json"
+    # 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 = f"v{release}"
+elif version_match == "stable":
+    version_match = f"v{release}"
+
 html_theme_options = {
     "use_edit_page_button": True,
     "icon_links": [
@@ -76,6 +115,16 @@
             "type": "fontawesome",
         },
     ],
+    "switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },
+    "logo": {
+        "text": "NWB GUIDE",
+        "alt_text": "NWB GUIDE - Home",
+    },
+    "navbar_start": ["navbar-logo", "version-switcher"],
+    "show_version_warning_banner": True,
 }
 
 html_context = {

docs/conf_extlinks.py

@@ -45,7 +45,11 @@
     "ontobee": ("https://ontobee.org/%s", None),
 
     "web-components": ("https://www.webcomponents.org/%s", None),
-    "npm": ("https://www.npmjs.com/%s", None)
+    "npm": ("https://www.npmjs.com/%s", None),
+
+    "sphinx": ("https://www.sphinx-doc.org/en/master/%s", None),
+    "pydata-sphinx-theme": ("https://pydata-sphinx-theme.readthedocs.io/en/stable/%s", None),
+    "readthedocs": ("https://docs.readthedocs.io/en/stable/%s", None),
 }
 
 # Use this for mapping for links to commonly used documentation

docs/developer_guide.rst

@@ -284,3 +284,24 @@ Code signing on Mac OS
 5. Review and agree to any pending agreements.
     a. Go to https://appstoreconnect.apple.com/agreements/#/ and agree to pending agreements for Free Apps.
     b. Review and agree to the Apple Developer Program License Agreement, which updates periodically.
+
+Updating the Documentation
+--------------------------
+
+The documentation is generated by :sphinx:`Sphinx <>` with the :pydata-sphinx-theme:`PyData Sphinx theme <>`.
+
+To build the documentation locally, run:
+
+.. code-block:: bash
+
+    cd docs
+    make html
+
+You can also run ``make clean`` from the ``docs`` directory to remove all files in the `docs/build` directory.
+
+The documentation is hosted online using :readthedocs:`ReadTheDocs <>`. An automation rule was set up so that
+new tags will automatically be activated; however, these versions are not automatically listed in the version
+switcher. ``docs/_static/switcher.json`` must be manually updated to specify new versions, remove versions
+that are too old, label a particular version as stable in the name, and identify which version is
+"preferred" for use in version warning banners. See
+:pydata-sphinx-theme:`PyData Sphinx theme user guide <user_guide>` for instructions and more information.

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements-rtd.txt

@@ -2,6 +2,7 @@ numpy
 jsonschema==3.2.0
 Jinja2<3.1
 sphinx==5.1.1
-pydata-sphinx-theme==0.14.1
+pydata-sphinx-theme==0.15.2
 readthedocs-sphinx-search==0.3.2
 sphinx-copybutton==0.5.0
+sphinx-favicon==1.0.1