Add sphinx docs...

Author: isaacrobinson2000

.gitignore

@@ -5,3 +5,5 @@ result_images
 .pytest_cache
 dist
 *.egg-info
+docs/_build/
+docs/api/generated

docs/Makefile

@@ -0,0 +1,20 @@
+# 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
+
+# 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)

docs/api/index.rst

@@ -0,0 +1,13 @@
+API
+===
+
+The public facing functions of matplotview.
+
+.. autosummary::
+    :toctree: generated
+
+    matplotview.view
+    matplotview.stop_viewing
+    matplotview.inset_zoom_axes
+
+

docs/conf.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+import sys
+
+# Add project root directory to python path...
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+
+project = 'matplotview'
+copyright = '2022, Isaac Robinson'
+author = 'Isaac Robinson'
+release = '1.0.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+    'numpydoc',
+    'matplotlib.sphinxext.mathmpl',
+    'matplotlib.sphinxext.plot_directive',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+plot_include_source = True

docs/examples/index.rst

@@ -0,0 +1,16 @@
+Examples
+========
+
+Because of the way matplotview is designed, it can work with any Axes and projection
+types, and works with all the default projection modes included in matplotlib.
+The following examples showcase using matplotview in several different scenarios and
+with different projections.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Examples:
+
+    plots/simplest_example
+    plots/multiple_artist_view
+    plots/simple_inset_view
+    plots/sierpinski_triangle

docs/examples/plots/multiple_artist_view.rst

@@ -0,0 +1,30 @@
+A View With Several Plot Elements
+=================================
+
+A simple example with an assortment of plot elements.
+
+.. plot::
+
+    from matplotview import view
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    fig, (ax1, ax2) = plt.subplots(1, 2)
+
+    # Plot a line, circle patch, some text, and an image...
+    ax1.plot([i for i in range(10)], "r")
+    ax1.add_patch(plt.Circle((3, 3), 1, ec="black", fc="blue"))
+    ax1.text(10, 10, "Hello World!", size=20)
+    ax1.imshow(np.random.rand(30, 30), origin="lower", cmap="Blues", alpha=0.5,
+               interpolation="nearest")
+
+    # Turn axes 2 into a view of axes 1.
+    view(ax2, ax1)
+    # Modify the second axes data limits to match the first axes...
+    ax2.set_aspect(ax1.get_aspect())
+    ax2.set_xlim(ax1.get_xlim())
+    ax2.set_ylim(ax1.get_ylim())
+
+    fig.tight_layout()
+    fig.show()
+

docs/examples/plots/sierpinski_triangle.rst

@@ -0,0 +1,48 @@
+Sierpiński Triangle With Recursive Views
+========================================
+
+Matplotview's views support recursive drawing of other views and themselves to a
+configurable depth. This feature allows matplotview to be used to generate fractals,
+such as a sierpiński triangle as shown in the following example.
+
+.. plot::
+
+    import matplotlib.pyplot as plt
+    import matplotview as mpv
+    from matplotlib.patches import PathPatch
+    from matplotlib.path import Path
+    from matplotlib.transforms import Affine2D
+
+    # We'll plot a white upside down triangle inside of black one, and then use
+    # 3 views to draw all the rest of the recursions of the sierpiński triangle.
+    outside_color = "black"
+    inner_color = "white"
+
+    t = Affine2D().scale(-0.5)
+
+    outer_triangle = Path.unit_regular_polygon(3)
+    inner_triangle = t.transform_path(outer_triangle)
+    b = outer_triangle.get_extents()
+
+    fig, ax = plt.subplots(1)
+    ax.set_aspect(1)
+
+    ax.add_patch(PathPatch(outer_triangle, fc=outside_color, ec=[0] * 4))
+    ax.add_patch(PathPatch(inner_triangle, fc=inner_color, ec=[0] * 4))
+    ax.set_xlim(b.x0, b.x1)
+    ax.set_ylim(b.y0, b.y1)
+
+    ax_locs = [
+        [0, 0, 0.5, 0.5],
+        [0.5, 0, 0.5, 0.5],
+        [0.25, 0.5, 0.5, 0.5]
+    ]
+
+    for loc in ax_locs:
+        inax = mpv.inset_zoom_axes(ax, loc, render_depth=6)
+        inax.set_xlim(b.x0, b.x1)
+        inax.set_ylim(b.y0, b.y1)
+        inax.axis("off")
+        inax.patch.set_visible(False)
+
+    fig.show()

docs/examples/plots/simple_inset_view.rst

@@ -0,0 +1,45 @@
+Create Inset Axes Without Plotting Twice
+========================================
+
+:meth:`matplotview.inset_zoom_axes` can be utilized to create inset axes where we
+don't have to plot the parent axes data twice.
+
+.. plot::
+
+    from matplotlib import cbook
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from matplotview import inset_zoom_axes
+
+    def get_demo_image():
+        z = cbook.get_sample_data("axes_grid/bivariate_normal.npy", np_load=True)
+        # z is a numpy array of 15x15
+        return z, (-3, 4, -4, 3)
+
+    fig, ax = plt.subplots()
+
+    # Make the data...
+    Z, extent = get_demo_image()
+    Z2 = np.zeros((150, 150))
+    ny, nx = Z.shape
+    Z2[30:30+ny, 30:30+nx] = Z
+
+    ax.imshow(Z2, extent=extent, interpolation='nearest', origin="lower")
+
+    # Creates an inset axes with automatic view of the parent axes...
+    axins = inset_zoom_axes(ax, [0.5, 0.5, 0.47, 0.47])
+    # Set limits to sub region of the original image
+    x1, x2, y1, y2 = -1.5, -0.9, -2.5, -1.9
+    axins.set_xlim(x1, x2)
+    axins.set_ylim(y1, y2)
+
+    # Remove the tick labels from the inset axes
+    axins.set_xticklabels([])
+    axins.set_yticklabels([])
+
+    # Draw the indicator or zoom lines.
+    ax.indicate_inset_zoom(axins, edgecolor="black")
+
+    fig.show()
+
+

docs/examples/plots/simplest_example.rst

@@ -0,0 +1,25 @@
+The Simplest View
+=================
+
+The simplest example: We make a view of a line! Views can be created quickly
+using :meth:`matplotview.view` .
+
+.. plot::
+
+    from matplotview import view
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    fig, (ax1, ax2) = plt.subplots(1, 2)
+
+    # Plot a line in the first axes.
+    ax1.plot([i for i in range(10)], "-o")
+
+    # Create a view! Turn axes 2 into a view of axes 1.
+    view(ax2, ax1)
+    # Modify the second axes data limits so we get a slightly zoomed out view
+    ax2.set_xlim(-5, 15)
+    ax2.set_ylim(-5, 15)
+
+    fig.show()
+

docs/index.rst

@@ -0,0 +1,23 @@
+.. matplotview documentation master file, created by
+   sphinx-quickstart on Sat Aug 13 19:55:28 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Matplotview |release| Documentation
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   examples/index
+   api/index
+
+
+Additional Links
+================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`