create docs page

.gitignore

@@ -32,3 +32,6 @@ ipympl/labextension
 
 # OS specific items
 .DS_Store
+
+# sphinx build dir
+docs/_build

dev-environment.yml

@@ -13,5 +13,14 @@ dependencies:
     - flake8
     - pytest
     - nbval
+    - pre-commit
     - pip:
         - build
+        - myst-nb
+        - Sphinx >= 1.5
+        - sphinx-copybutton
+        - sphinx-panels
+        - sphinx-thebe
+        - sphinx-togglebutton
+        - sphinx-book-theme
+        - sphinx-autobuild

docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -T --color
+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
+
+# 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)
+
+watch:
+	sphinx-autobuild . _build/html --open-browser --watch examples

docs/_static/custom.css

@@ -0,0 +1,12 @@
+/* Fix numpydoc format delimiters */
+.classifier:before {
+  font-style: normal;
+  margin: 0.5em;
+  content: ":";
+}
+
+/* override table no-wrap */
+.wy-table-responsive table td,
+.wy-table-responsive table th {
+  white-space: normal;
+}

docs/conf.py

@@ -0,0 +1,185 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+import inspect
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+try:
+    from ipympl import __version__ as release
+except ImportError:
+    release = "unknown"
+
+
+# -- Project information -----------------------------------------------------
+
+project = "ipympl"
+copyright = "2022, Matplotlib Development Team"
+author = "Matplotlib Development Team"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "jupyter_sphinx",
+    "myst_nb",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.linkcode",
+    "sphinx.ext.mathjax",
+    "sphinx_copybutton",
+    "sphinx_panels",
+    "sphinx_thebe",
+    "sphinx_togglebutton",
+]
+
+
+# Cross-referencing configuration
+default_role = "py:obj"
+primary_domain = "py"
+nitpicky = True  # warn if cross-references are missing
+
+# Intersphinx settings
+intersphinx_mapping = {
+    "ipywidgets": ("https://ipywidgets.readthedocs.io/en/stable", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "python": ("https://docs.python.org/3", None),
+}
+
+# remove panels css to get wider main content
+panels_add_bootstrap_css = False
+
+# Settings for copybutton
+copybutton_prompt_is_regexp = True
+copybutton_prompt_text = r">>> |\.\.\. "  # doctest
+
+# Settings for linkcheck
+linkcheck_anchors = False
+linkcheck_ignore = []  # type: ignore
+
+execution_timeout = -1
+jupyter_execute_notebooks = "off"
+if "EXECUTE_NB" in os.environ:
+    print("\033[93;1mWill run Jupyter notebooks!\033[0m")
+    jupyter_execute_notebooks = "force"
+
+# Settings for myst-parser
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "dollarmath",
+    "smartquotes",
+    "substitution",
+]
+suppress_warnings = [
+    "myst.header",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "**ipynb_checkpoints",
+    ".DS_Store",
+    "Thumbs.db",
+    "_build",
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_copy_source = True  # needed for download notebook button
+html_css_files = [
+    "custom.css",
+]
+html_sourcelink_suffix = ""
+html_static_path = ["_static"]
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "launch_buttons": {
+        "binderhub_url": "https://mybinder.org",
+        "colab_url": "https://colab.research.google.com",
+        "notebook_interface": "jupyterlab",
+        "thebe": True,
+        "thebelab": True,
+    },
+    "path_to_docs": "docs",
+    "repository_branch": "main",
+    "repository_url": "https://github.com/matplotlib/ipympl",
+    "use_download_button": True,
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+}
+html_title = "ipympl"
+
+master_doc = "index"
+thebe_config = {
+    "repository_url": html_theme_options["repository_url"],
+    "repository_branch": html_theme_options["repository_branch"],
+}
+
+
+# based on pandas/doc/source/conf.py
+def linkcode_resolve(domain, info):
+    """
+    Determine the URL corresponding to Python object
+    """
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    try:
+        fn = inspect.getsourcefile(inspect.unwrap(obj))
+    except TypeError:
+        fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except OSError:
+        lineno = None
+
+    if lineno:
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
+    else:
+        linespec = ""
+
+    fn = os.path.relpath(fn, start=os.path.dirname("../ipympl"))
+
+    return (
+        f"https://github.com/matplotlib/ipympl/blob/main/ipympl/{fn}{linespec}"  # noqa
+    )

docs/contributing.md

@@ -0,0 +1,92 @@
+# 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/matplotlib/ipympl/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 [here](https://github.com/matplotlib/ipympl). 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)).
+
+The below instructions use [Mamba](https://github.com/mamba-org/mamba#the-fast-cross-platform-package-manager) which is a very fast implementation of `conda`.
+
+```bash
+git clone <your fork>
+cd ipympl
+mamba env create --file dev-environment.yml
+conda activate ipympl-dev
+pre-commit install
+```
+
+Install the Python Packge
+```bash
+pip install -e .
+```
+
+When developing your extensions, you need to manually enable your extensions with the
+notebook / lab frontend. For lab, this is done by the command:
+
+```bash
+jupyter labextension develop --overwrite .
+yarn run build
+```
+
+For classic notebook, you need to run:
+```bash
+jupyter nbextension install --py --symlink --sys-prefix --overwrite ipympl
+jupyter nbextension enable --py --sys-prefix ipympl
+```
+
+
+
+### How to see your changes
+
+**Typescript**:
+
+If you use JupyterLab to develop then you can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the widget.
+
+```bash
+# Watch the source directory in one terminal, automatically rebuilding when needed
+yarn run watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
+
+After a change wait for the build to finish and then refresh your browser and the changes should take effect.
+
+**Python:**
+
+If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
+
+
+## Documentation
+
+Our documentation is built with [Sphinx](https://www.sphinx-doc.org) from the notebooks in the `docs` folder. It contains both Markdown files and Jupyter notebooks.
+
+Examples are best written as Jupyter notebooks. To write a new example, create in a notebook in the `docs/examples` directory and list its path under one of the [`toctree`s](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) in the `index.ipynb` file. When the docs are generated, they will be rendered as static html pages by [myst-nb](https://myst-nb.readthedocs.io).
+
+If you have installed all developer dependencies (see [above](#contributing)), you can rebuild the docs with the following `make` command run from inside the `docs` folder:
+
+```
+make html
+```
+
+Then you can open the `_build/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 in the dev environment you created earlier so all you need to do is run
+
+```bash
+make watch
+```
+from inside the `docs` folder
+
+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!
+
+## 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/matplotlib/ipympl/issues).
+
+
+## Getting Help contributing
+
+Feel free to ask questions about how to contribute on any Github Issue. You can also ask shorter questions on the [gitter chatroom](https://gitter.im/jupyter-widgets/Lobby).