Improve docs (#15)

* update docs

* add docs of sphinx-gallery

* fixes

Author: ianhi

doc/commandline.md

@@ -0,0 +1,16 @@
+# Command Line Usage
+
+**recording interactions**
+To record a json file for later playback:
+```bash
+python -m mpl_playback.record example_file.py -figures fig --output example_playback.json
+```
+
+This will launch example_file.py and record any interactions with the object named `fig`. Then it will be saved to `example_playback.json`. However, the output argument is optional, if not given then the name will be `example_file-playback.json`
+
+**playback interactions in a gif**
+To play back the file you must pass both the original python file and the recording json file. You can optionally pass names for the output gif(s) with the `--output` argument, or allow the names to be chosen automatically. 1 gif will be created for each figure that was recorded.
+
+```bash
+python -m mpl_playback.playback example_file.py example_playback.json
+```

doc/conf.py

@@ -33,6 +33,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "myst_nb",
     "sphinx_gallery.gen_gallery",
 ]
 

doc/contributing.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thanks for thinking of a way to help improve this library! Remember that contributions come in all shapes and sizes beyond writing bug fixes. Contributing to [documentation](#documentation), opening new [issues](https://github.com/ianhi/mpl-playback/issues) for bugs, asking for clarification on things you find unclear, and requesting new features, are all super valuable contributions.
+
+## Code Improvements
+
+All development for this library happens on GitHub at [mpl-playback](https://github.com/ianhi/mpl-playback). We recommend you work with a [Conda](https://www.anaconda.com/products/individual) environment (or an alternative virtual environment like [`venv`](https://docs.python.org/3/library/venv.html)).
+
+```bash
+git clone <your fork>
+cd mpl-playback
+mamba env create -n mpl-playback python matplotlib -c conda-forge
+conda activate mpl-playback
+pip install pre-commit
+pre-commit install
+```
+
+The `mamba env create` command installs all Python packages that are useful when working on the source code of `mpl_playback` and its documentation. You can also install these packages separately:
+
+```bash
+pip install -e .[doc]
+```
+
+The {command}`-e .` flag installs the `mpl_playback` folder in ["editable" mode](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs) and {command}`[dev]` installs the [optional dependencies](https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies) you need for developing `mpl_playback`.
+
+### Seeing your changes
+
+If you are working in a Jupyter Notebook, then in order to see your code changes you will need to either:
+
+- Restart the Kernel every time you make a change to the code.
+- Make the function reload from the source file every time you run it by using [autoreload](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html), e.g.:
+
+  ```python
+  %load_ext autoreload
+  %autoreload 2
+  from mpl_playback import ....
+  ```
+
+### Working with Git
+
+Using Git/GitHub can confusing (<https://xkcd.com/1597>), so if you're new to Git, you may find it helpful to use a program like [GitHub Desktop](https://desktop.github.com) and to follow a [guide](https://github.com/firstcontributions/first-contributions#first-contributions).
+
+Also feel free to ask for help/advice on the relevant GitHub [issue](https://github.com/ianhi/mpl-playback/issues).
+
+## Documentation
+
+Our documentation on Read the Docs ([mpl-playback.rtfd.io](https://mpl-playback.readthedocs.io)) is built with [Sphinx](https://www.sphinx-doc.org) from the notebooks in the `docs` folder. It contains both Markdown files and Jupyter notebooks.
+
+If you open the `index.html` file in your browser you should now be able to see the rendered documentation.
+
+Alternatively, you can use [sphinx-autobuild](https://github.com/executablebooks/sphinx-autobuild) to continuously watch source files for changes and rebuild the documentation for you. Sphinx-autobuild will be installed automatically by the above `pip` command, so all you need to do is run:
+
+```bash
+tox -e doclive
+```
+
+In a few seconds your web browser should open up the documentation. Now whenever you save a file the documentation will automatically regenerate and the webpage will refresh for you!

doc/index.md

@@ -0,0 +1,43 @@
+.. mpl-playback documentation master file, created by
+   sphinx-quickstart on Mon Jan 11 19:21:27 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+# Welcome to mpl-playback's documentation!
+
+A library to record and then playback user interactions with a Matplotlib
+figure. Also integrates with [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html)
+by providing a custom scraper so docs using widgets will render showing the interactions.
+See this in action in the :doc:`Gallery <gallery/index>`.
+
+Inspired by discussions here: https://github.com/matplotlib/matplotlib/issues/19222
+
+## Installation
+
+```bash
+pip install mpl-playback
+```
+
+```{note}
+If you are using for your sphinx-gallery docs build you should pin the version of `mpl-playback`.
+```
+
+### Q: Should you use this?
+A: Depends on what you want. For one off gifs of interactions it's almost certainly easier to just record your screen to make a gif. But if you want integration with `sphinx-gallery` then this is currently the only option.
+
+
+
+```{toctree}
+:maxdepth: 3
+
+gallery/index
+commandline
+sphinx-gallery
+contributing
+```
+
+### Indices and Tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`

doc/index.rst

@@ -0,0 +1,17 @@
+# Sphinx-gallery integration
+
+
+`mpl-playback` provides a custom [sphinx-gallery scraper](https://sphinx-gallery.github.io/stable/advanced.html#write-a-custom-image-scraper) which allows you automatically generate gifs for your interactive maptlotlib plots in your sphinx gallery. This custom scraper will generate a gif if there is a playback json file available, and otherwise will fall back to the default matplotlib scraper.
+
+To enable the custom scraper add the following to your `conf.py`
+
+
+```python
+from mpl_playback.scraper import matplotlib_scraper
+sphinx_gallery_conf = {
+    # ... the rest of your normal config
+    "image_scrapers": (matplotlib_scraper),
+}
+```
+
+then the scraper will automatically pick up any playback files that are in the same directory as the examples.

doc/sphinx-gallery.md

@@ -35,6 +35,7 @@ python_requires = >=3.8
 docs =
     Sphinx>=1.5
     furo
+    myst_nb
     sphinx-copybutton
     sphinx_gallery