Merge pull request #178 from LabForComputationalVision/fix_nbsphinx

Documentation improvements

CONTRIBUTING.md

@@ -320,8 +320,11 @@ make html
 
 We build tutorials as Jupyter notebooks so that they can be launched in Binder
 and people can play with them on their local machine. In order to include them
-in the built docs, add a `nblink` file to the `docs/tutorials/` directory. This
-is a json file that should contain the path to the notebook, like so, for
+in the built docs, add a `nblink` file to the `docs/tutorials/` directory. We
+check for this during the tests, so you won't be able to merge your pull request
+into `main` unless you've done this!
+
+This is a json file that should contain the path to the notebook, like so, for
 `docs/tutorials/my_awesome_tutorial.nblink`:
 
 ```
@@ -334,18 +337,8 @@ note that you *cannot* have a trailing comma there, because json is very
 particular. See the [nbsphinx-link](https://github.com/vidartf/nbsphinx-link)
 page for more details.
 
-Once you've done that, you should add it to our `index.rst`. Towards the bottom
-of that page, you'll find a `toctree` with the caption "Tutorials and examples".
-Add your new tutorial by adding the line `tutorials/my_awesome_tutorial.nblink`
-after the existing ones. Then, once you run `make html`, your tutorial should
-now be included!
-
 *NOTE*: In order for the `toctree` formatting to work correctly, your notebook
 should have exactly one H1 title (i.e., line starting with a single `#`), but
 you can have as many lower-level titles as you'd like. If you have multiple H1
 titles, they'll each show up as different tutorials. If you don't have an H1
 title, it won't show up at all.
-
-When you add a new tutorial, don't forget to add it to the `treebeard.yml` file
-so it can be tested (see last paragraph of the [testing
-notebooks](#testing-notebooks) section for details).

docs/index.rst

@@ -22,7 +22,7 @@ plenoptic
 
 |license-shield| |python-version-shield| |build| |tutorials| |zenodo|
 
-Currently there's nothing here! However, we'll expand it as we go
+plenoptic is currently under development.
 
 If anything is unclear, please `open an issue <https://github.com/LabForComputationalVision/plenoptic/issues>`_
 
@@ -34,20 +34,11 @@ If anything is unclear, please `open an issue <https://github.com/LabForComputat
    api/modules
 
 .. toctree::
-   :maxdepth: 1
+   :titlesonly:
+   :glob:
    :caption: Tutorials and examples
 
-   tutorials/00_simple_example.nblink
-   tutorials/01_Linear_approximation_of_nonlinear_model.nblink
-   tutorials/02_Eigendistortions.nblink
-   tutorials/03_Steerable_Pyramid.nblink
-   tutorials/04_Perceptual_distance.nblink
-   tutorials/05_Geodesics.nblink
-   tutorials/06_Metamer.nblink
-   tutorials/07_MAD_Competition.nblink
-   tutorials/08_Simple_MAD.nblink
-   tutorials/09_Original_MAD.nblink
-   tutorials/10_Synthesis.nblink
+   tutorials/*
 
 Indices and tables
 ==================

examples/06_Metamer.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Metamers\n",
+    "# Metamers\n",
     "\n",
     "Metamers are an old concept in the study of perception, dating back to the color-matching experiments in the 18th century that first provided support for the existence of three cone types (though it would be another two hundred years before anatomical evidence was found). These color-matching evidences demonstrated that, by combining three colored lights in different proportions, you could generate a color that humans perceived as identical to any other color, even though their physical spectra were different. Perceptual metamers, then, refer to two images that are physically different but perceived as identical.\n",
     "\n",

examples/testing-new-synthesis.ipynb

@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "255fbc00-a4b9-41ec-ade1-6fce1cc4eec6",
+   "metadata": {},
+   "source": [
+    "# Testing new synthesis methods"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,

plenoptic/metric/model_metric.py

@@ -7,7 +7,7 @@ def model_metric(x, y, model):
     Calculate distance between x and y in model space root mean squared error
 
     Parameters
-    -----------
+    ----------
     image: torch.Tensor
         image, (B x C x H x W)
     model: torch class
@@ -64,4 +64,4 @@ def model_metric(x, y, model):
 #
 #         dist = torch.sqrt(torch.mean((repx - repy) ** 2) + epsilon)
 #
-#         return dist
+#         return dist

plenoptic/simulate/canonical_computations/non_linearities.py

@@ -22,8 +22,9 @@ def rectangular_to_polar_dict(coeff_dict, dim=-1, residuals=False):
     state: dict
         The dictionary of torch.Tensors containing the local phase of
         ``coeff_dict``.
-    Note
-    ----
+
+    Notes
+    -----
     Since complex numbers are not supported by pytorch, we represent
     complex tensors as having an extra dimension with two slices, where
     one contains the real and the other contains the imaginary

plenoptic/simulate/canonical_computations/steerable_pyramid_freq.py

@@ -440,7 +440,7 @@ def convert_pyr_to_tensor(pyr_coeffs, split_complex=False):
             channel. This should be True if you intend to use a convolutional layer on top of the output. 
 
         Returns
-        -----------
+        -------
         pyr_tensor: `torch.Tensor` (BxCxHxW)
             pyramid coefficients reshaped into tensor. The first channel will be the residual highpass and the last will be
             the residual lowpass. Each band is then a separate channel. 
@@ -521,7 +521,7 @@ def convert_tensor_to_pyr(pyr_tensor, num_channels, split_complex, pyr_keys):
            pyr_dict = convert_tensor_to_pyr(pyr_tensor, *pyr_info)
 
         Returns
-        ----------
+        -------
         pyr_coeffs: `OrderedDict`
             pyramid coefficients in dictionary format
         """

plenoptic/simulate/models/portilla_simoncelli.py

@@ -51,7 +51,7 @@ class PortillaSimoncelli(nn.Module):
         A dictionary containing the Portilla-Simoncelli statistics
 
     References
-    -----
+    ----------
     .. [1] J Portilla and E P Simoncelli. A Parametric Texture Model based on
        Joint Statistics of Complex Wavelet Coefficients. Int'l Journal of
        Computer Vision. 40(1):49-71, October, 2000.

plenoptic/synthesize/eigendistortion.py

@@ -80,7 +80,7 @@ class Eigendistortion:
         Index of each eigenvector/eigenvalue.
 
     Parameters
-    -----------
+    ----------
     base_signal
         Image, torch.Size(batch=1, channel, height, width). We currently do not support batches of images,
         as each image requires its own optimization.

plenoptic/synthesize/geodesic.py

@@ -56,8 +56,8 @@ class Geodesic(nn.Module):
         measures distance from straight line and distance along straight line,
         stored along the optimization process
 
-    Note
-    ----
+    Notes
+    -----
     Manifold prior hypothesis: natural images form a manifold 𝑀ˣ embedded
     in signal space (ℝⁿ), a model warps this manifold to another manifold 𝑀ʸ
     embedded in representation space (ℝᵐ), and thereby induces a different

plenoptic/tools/data.py

@@ -274,7 +274,7 @@ def polar_radius(
     function, raised to given exponent, centered at given origin.
 
     Parameters
-    ---------
+    ----------
     size
         If an int, we assume the image should be of dimensions `(size,
         size)`. if a tuple, must be a 2-tuple of ints specifying the
@@ -335,7 +335,7 @@ def polar_angle(
     X-axis, ranging from -pi to pi), relative to given phase, about the given origin pixel.
 
     Parameters
-    ---------
+    ----------
     size
         If an int, we assume the image should be of dimensions `(size, size)`. if a tuple, must be
         a 2-tuple of ints specifying the dimensions

plenoptic/tools/display.py

@@ -24,8 +24,8 @@ def imshow(image, vrange='indep1', zoom=None, title='', col_wrap=None, ax=None,
     image that's 2000 pixels wide on an monitor 1000 pixels wide; the notebook
     handles the rescaling in a way we can't control).
 
-    Arguments
-    ---------
+    Parameters
+    ----------
     image : torch.Tensor or list
         The images to display. Tensors should be 4d (batch, channel, height,
         width). List of tensors should be used for tensors of different height
@@ -189,8 +189,8 @@ def animshow(video, framerate=2., repeat=False, vrange='indep1', zoom=1,
     ``anim.save(filename)`` (note for this that you'll need the appropriate
     writer installed and on your path, e.g., ffmpeg, imagemagick, etc).
 
-    Arguments
-    ---------
+    Parameters
+    ----------
     video : torch.Tensor or list
         The videos to display. Tensors should be 5d (batch, channel, time,
         height, width). List of tensors should be used for tensors of different
@@ -604,8 +604,8 @@ def clean_stem_plot(data, ax=None, title='', ylim=None, xvals=None, **kwargs):
     ax : `matplotlib.pyplot.axis`
         The axis with the plot
 
-    Example
-    -------
+    Examples
+    --------
     We allow for breaks in the baseline value if we want to visually
     break up the plot, as we see below.
 

plenoptic/tools/signal.py

@@ -84,7 +84,7 @@ def raised_cosine(
     This lookup table is suitable for use by `interpolate1d`
 
     Parameters
-    ---------
+    ----------
     width
         The width of the region over which the transition occurs.
     position
@@ -152,7 +152,7 @@ def rectangular_to_polar(x: Tensor) -> Tuple[Tensor, Tensor]:
     r"""Rectangular to polar coordinate transform
 
     Parameters
-    --------
+    ----------
     x
         Complex tensor.
 

plenoptic/tools/straightness.py

@@ -128,7 +128,7 @@ def translation_sequence(image, n_steps=10):
     """make a horizontal translation sequence on `image`
 
     Parameters
-    ---------
+    ----------
     image: torch.Tensor
         Base image of shape, [C, H, W]
     n_steps: int, optional