diff --git a/.github/workflows/chromatic.yml b/.github/workflows/chromatic.yml index 09b74deac..43b4967b6 100644 --- a/.github/workflows/chromatic.yml +++ b/.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: diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 01c3cb79d..93595548e 100644 --- a/.readthedocs.yaml +++ b/.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: diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..1ed9f07ce --- /dev/null +++ b/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) diff --git a/docs/_static/android-chrome-192x192.png b/docs/_static/android-chrome-192x192.png new file mode 100644 index 000000000..b0d05c873 Binary files /dev/null and b/docs/_static/android-chrome-192x192.png differ diff --git a/docs/_static/android-chrome-512x512.png b/docs/_static/android-chrome-512x512.png new file mode 100644 index 000000000..1aea6cbaf Binary files /dev/null and b/docs/_static/android-chrome-512x512.png differ diff --git a/docs/_static/apple-touch-icon.png b/docs/_static/apple-touch-icon.png new file mode 100644 index 000000000..33ce4a5a9 Binary files /dev/null and b/docs/_static/apple-touch-icon.png differ diff --git a/docs/_static/favicon-16x16.png b/docs/_static/favicon-16x16.png new file mode 100644 index 000000000..cda9624f8 Binary files /dev/null and b/docs/_static/favicon-16x16.png differ diff --git a/docs/_static/favicon-32x32.png b/docs/_static/favicon-32x32.png new file mode 100644 index 000000000..9c8f1f197 Binary files /dev/null and b/docs/_static/favicon-32x32.png differ diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 000000000..62ff34ee2 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json new file mode 100644 index 000000000..ed9b35e2c --- /dev/null +++ b/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 + } +] diff --git a/docs/assets/logo-guide-draft-transparent-tight.png b/docs/assets/logo-guide-draft-transparent-tight.png new file mode 100644 index 000000000..eb2d6cbfa Binary files /dev/null and b/docs/assets/logo-guide-draft-transparent-tight.png differ diff --git a/docs/conf.py b/docs/conf.py index 71360409d..52a59ff6f 100644 --- a/docs/conf.py +++ b/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 = { diff --git a/docs/conf_extlinks.py b/docs/conf_extlinks.py index e6565f3c3..2ccfc42c3 100644 --- a/docs/conf_extlinks.py +++ b/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 diff --git a/docs/developer_guide.rst b/docs/developer_guide.rst index e457888da..32e99f6fb 100644 --- a/docs/developer_guide.rst +++ b/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 ` for instructions and more information. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..3d64bb3aa --- /dev/null +++ b/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 diff --git a/docs/requirements-rtd.txt b/docs/requirements-rtd.txt index e054f77c5..607adaad3 100644 --- a/docs/requirements-rtd.txt +++ b/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