From 974de6153891c6367348a4c24b12b59258ccc82b Mon Sep 17 00:00:00 2001 From: Ian Hunt-Isaak Date: Sun, 17 Jul 2022 22:04:25 -0500 Subject: [PATCH] Improve docs (#15) * update docs * add docs of sphinx-gallery * fixes --- doc/commandline.md | 16 ++++++++++++ doc/conf.py | 1 + doc/contributing.md | 57 +++++++++++++++++++++++++++++++++++++++++++ doc/index.md | 43 ++++++++++++++++++++++++++++++++ doc/index.rst | 37 ---------------------------- doc/sphinx-gallery.md | 17 +++++++++++++ setup.cfg | 1 + 7 files changed, 135 insertions(+), 37 deletions(-) create mode 100644 doc/commandline.md create mode 100644 doc/contributing.md create mode 100644 doc/index.md delete mode 100644 doc/index.rst create mode 100644 doc/sphinx-gallery.md diff --git a/doc/commandline.md b/doc/commandline.md new file mode 100644 index 0000000..ae438af --- /dev/null +++ b/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 +``` diff --git a/doc/conf.py b/doc/conf.py index 177a12e..cd87899 100644 --- a/doc/conf.py +++ b/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", ] diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000..33d307c --- /dev/null +++ b/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 +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 (), 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! diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..4f9d746 --- /dev/null +++ b/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 `. + +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` diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 7890bb0..0000000 --- a/doc/index.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. 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 `_ -by providing a custom scraper so docs using widgets will render showing the interactions. -See this in action in the :doc:`Gallery `. - -Inspired by discussions here: https://github.com/matplotlib/matplotlib/issues/19222 - -Q: Should you use this? - -A: Probably not. I mainly made this so that I could more easily test widget interactions https://github.com/ianhi/mpl-interactions - -For one off gifs of interactions it's almost certainly easier to just record your screen to make a gif. - -Developed on https://github.com/ianhi/mpl-playback PRs or comments welcome :) - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - gallery/index.rst - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/sphinx-gallery.md b/doc/sphinx-gallery.md new file mode 100644 index 0000000..9ec6475 --- /dev/null +++ b/doc/sphinx-gallery.md @@ -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. diff --git a/setup.cfg b/setup.cfg index 7b1dc1e..185f5c1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -35,6 +35,7 @@ python_requires = >=3.8 docs = Sphinx>=1.5 furo + myst_nb sphinx-copybutton sphinx_gallery