Documentation set up with Sphinx (#200)

Supersedes #173 
May close #80 
@melissawm implements the sphinx documentation setup, similar to the napari/docs repository documentation setup
@GenevieveBuckley adds scrapers for the examples gallery (for videos and static napari screenshots), and adds the github actions docs deployment

.github/workflows/deploy_docs.yml

@@ -0,0 +1,60 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+# Only allow one docs build at a time so that overlapping stale builds will get
+# cancelled automatically.
+concurrency:
+  group: deploy_docs
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    name: Build & Deploy
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # so we can write to github pages without a token
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    steps:
+    - name: Clone repo
+      uses: actions/checkout@v4
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+
+    - uses: tlambert03/setup-qt-libs@v1
+
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install "napari[all]"
+        python -m pip install -e ".[doc]"
+
+    - name: Build Docs
+      uses: aganders3/headless-gui@v2
+      with:
+        run: make docs
+
+    - name: Check file tree contents
+      run: tree
+
+    # At a minimum this job should upload artifacts using actions/upload-pages-artifact
+    - name: Upload GitHub Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        name: github-pages
+        path: docs/_build
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

.gitignore

@@ -80,4 +80,11 @@ target/
 */_version.py
 
 # vscode
-.vscode
+.vscode
+
+# Autogenerated gallery
+docs/gallery
+docs/jupyter_execute
+docs/sg_execution_times.rst
+examples/*.mov
+examples/*.mp4

Makefile

@@ -0,0 +1,46 @@
+.PHONY: docs clean
+
+SPHINXOPTS =
+
+mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
+current_dir := $(dir $(mkfile_path))
+docs_dir := $(current_dir)docs
+
+clean:
+	echo clean
+	echo $(current_dir)
+	rm -rf $(docs_dir)/_build/
+	rm -rf $(docs_dir)/gallery/
+	rm -f $(docs_dir)/sg_execution_times.rst
+
+docs-build:
+	NAPARI_CONFIG="" NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b html docs/ docs/_build $(SPHINXOPTS)
+
+docs-xvfb:
+	NAPARI_CONFIG="" NAPARI_APPLICATION_IPY_INTERACTIVE=0 xvfb-run --auto-servernum sphinx-build -b html docs/ docs/_build $(SPHINXOPTS)
+
+docs: clean docs-build copy-gallery-videos
+
+# Implies noplot, but no clean - call 'make clean' manually if needed
+# Autogenerated paths need to be ignored to prevent reload loops
+html-live:
+	NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
+	sphinx-autobuild \
+		-b html \
+		docs/ \
+		docs/_build \
+		-D plot_gallery=0 \
+		--ignore $(docs_dir)"/gallery/*" \
+		--ignore $(docs_dir)"/jupyter_execute/*" \
+		--open-browser \
+		--port=0 \
+		$(SPHINXOPTS)
+
+html-noplot: clean
+	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -D plot_gallery=0 -b html docs/ docs/_build $(SPHINXOPTS)
+
+linkcheck-files:
+	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build ${FILES} $(SPHINXOPTS)
+
+copy-gallery-videos:
+	rsync -rupE docs/gallery/images docs/_build/gallery

README.md

@@ -6,7 +6,7 @@
 [![tests](https://github.com/napari/napari-animation/actions/workflows/test_and_deploy.yml/badge.svg)](https://github.com/napari/napari-animation/actions)
 [![codecov](https://codecov.io/gh/napari/napari-animation/branch/main/graph/badge.svg)](https://codecov.io/gh/napari/napari-animation)
 
-**napari-animation** is a plugin for making animations in [napari].
+**napari-animation** is a plugin for making animations in [napari](https://napari.org).
 
 <p align="center">
   <img width="500" src="https://user-images.githubusercontent.com/7307488/196110138-6c4663b1-67b2-4c79-97b7-57b706d1d49c.gif">
@@ -18,14 +18,16 @@
 
 ----------------------------------
 
-This plugin is built on [naparimovie](https://github.com/guiwitz/naparimovie) from @guiwitz. naparimovie was submitted to napari in [PR#851](https://github.com/napari/napari/pull/780) before napari plugin infrastructure existed.
+This plugin is built on [`naparimovie`](https://github.com/guiwitz/naparimovie) from [@guiwitz](https://github.com/guiwitz). `naparimovie` was submitted to napari in [PR#851](https://github.com/napari/napari/pull/780) before napari plugin infrastructure existed.
 
 ----------------------------------
+
 ## Overview
 
-**napari-animation** provides a framework for the creation of animations in napari, the plugin contains:
-- an easy to use GUI for creating animations interactively
-- a Python package for the programmatic creation of animations
+**napari-animation** provides a framework for the creation of animations in napari. The plugin contains:
+
+- an easy to use GUI for creating animations interactively;
+- a Python package for the programmatic creation of animations.
 
 This plugin remains under development and contributions are very welcome, please open an issue to discuss potential improvements.
 
@@ -38,11 +40,12 @@ This plugin remains under development and contributions are very welcome, please
 pip install napari-animation
 ```
 
-> [!WARNING]
-> `napari-animation` uses `ffmpeg` to export animations. If you are using a macOS arm64 computer (Apple Silicon e.g. M1, M2 processor)
-> the PyPI package does not include the needed binary for your platform. You will need to install `ffmpeg` using
-> `conda` from the [conda-forge channel](https://conda-forge.org/docs/#what-is-conda-forge) (`conda install -c conda-forge ffmpeg`)
-> or using [`homebrew`](https://brew.sh) (`brew install ffmpeg`).
+```{warning}
+`napari-animation` uses `ffmpeg` to export animations. If you are using a macOS arm64 computer (Apple Silicon e.g. M1, M2 processor)
+the PyPI package does not include the needed binary for your platform. You will need to install `ffmpeg` using
+`conda` from the [conda-forge channel](https://conda-forge.org/docs/#what-is-conda-forge) (`conda install -c conda-forge ffmpeg`)
+or using [`homebrew`](https://brew.sh) (`brew install ffmpeg`).
+```
 
 ### Conda
 `napari-animation` is also available for install using `conda` through the [conda-forge channel](https://conda-forge.org/docs/#what-is-conda-forge).
@@ -71,8 +74,8 @@ To activate the GUI, select **napari-animation: wizard** from the *plugins menu*
   <img width="200" src="https://user-images.githubusercontent.com/7307488/196114466-56cb5985-0d79-4cfa-96f1-38cf3ccfbc48.png">
 </p>
 
-### Headless
-**napari-animation** can also be run headless, allowing for reproducible, scripted creation of animations.
+### Scripting
+**napari-animation** can also be run programatically, allowing for reproducible, scripted creation of animations.
 
 ```python
 from napari_animation import Animation
@@ -95,17 +98,22 @@ animation.animate('demo.mov', canvas_only=False)
 ```
 
 ## Examples
-Examples can be found in our [examples](examples) folder. Simple examples for both interactive and headless 
+Examples can be found in our [Examples gallery](https://napari-animation.github.io/gallery) folder. Simple examples for both interactive and headless 
 use of the plugin follow.
 
 ## Contributing
 
 Contributions are very welcome and a detailed contributing guide is coming soon.
 In the meantime, clone this repository and install it in editable mode using `pip`. 
 We recommend using a virtual environment, for example `conda`.
-> [!IMPORTANT]
-> Ensure you have a suitable Qt backend for napari! We recommend `PyQt5`.
-> For more information, see the napari [Qt backend installation guide](https://napari.org/stable/tutorials/fundamentals/installation.html#choosing-a-different-qt-backend)
+
+
+```{important}
+Ensure you have a suitable Qt backend for napari! We recommend `PyQt5`.
+For more information, see the napari [Qt backend installation guide](https://napari.org/stable/tutorials/fundamentals/installation.html#choosing-a-different-qt-backend)
+```
+
+To set up your development installation, clone this repository, navigate to the clone folder, and install napari-animation in editable mode using `pip`.
 
 ```sh
 conda create -n nap-anim python=3.10
@@ -118,26 +126,42 @@ Tests are run with `pytest`.
 You can make sure your `[dev]` installation is working properly by running
 `pytest .` from within the repository.
 
-> [!NOTE]
-> We use [`pre-commit`](https://pre-commit.com) to sort imports and lint with
-> [`ruff`](https://github.com/astral-sh/ruff) and format code with
-> [`black`](https://github.com/psf/black) automatically prior to each commit.
-> To minmize test errors when submitting pull requests, please install `pre-commit`
-> in your environment as follows:
-> ```sh
-> pre-commit install
-> ```
+```{note}
+We use [`pre-commit`](https://pre-commit.com) to sort imports and lint with
+[`ruff`](https://github.com/astral-sh/ruff) and format code with
+[`black`](https://github.com/psf/black) automatically prior to each commit.
+To minmize test errors when submitting pull requests, please install `pre-commit`
+in your environment as follows:
+
+`pre-commit install`
+```
+
+## Documentation
+
+The documentation for napari-animation is built with [Sphinx](https://www.spinx-doc.org). After installing the documentation dependencies with
+
+```sh
+pip install ".[doc]"
+```
+
+you can see a local version of the documentation by running
+
+```sh
+make docs
+```
+
+Open up the `docs/_build/index.html` file in your browser, and you'll see the home page of the docs being displayed.
+
 
 ## License
 
-Distributed under the terms of the [BSD-3] license,
-"napari-animation" is free and open source software
+Distributed under the terms of the [BSD-3 license](http://opensource.org/licenses/BSD-3-Clause),
+`napari-animation` is free and open source software.
 
 ## Issues
 
-If you encounter any problems, please [file an issue] along with a detailed description.
+If you encounter any problems, please [file an issue](https://github.com/napari/napari-animation/issues) along with a detailed description.
 
-[napari]: https://github.com/napari/napari
 [Cookiecutter]: https://github.com/audreyr/cookiecutter
 [@napari]: https://github.com/napari
 [BSD-3]: http://opensource.org/licenses/BSD-3-Clause

docs/_templates/navbar-project.html

@@ -0,0 +1,4 @@
+<!-- A small template snippet for theme testing -->
+<a class="navbar-brand" href="{{ pathto(master_doc) }}">
+  napari-animation
+</a>

docs/_toc.yml

@@ -0,0 +1,5 @@
+root: index
+subtrees:
+- entries:
+  - file: gallery
+  - file: developers/contributing