Merge pull request #209 from LabForComputationalVision/pip

Pip

.github/workflows/deploy.yml

@@ -0,0 +1,25 @@
+name: deploy
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build --outdir dist/ --sdist
+      - name: Publish package to test pypi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

CONTRIBUTING.md

@@ -95,6 +95,40 @@ objects](https://plenoptic.readthedocs.io/en/latest/synthesis.html). Any new
 models or synthesis objects will need to meet the requirements outlined in those
 pages.
 
+### Releases
+
+We create releases on Github, deploy on / distribute via
+[pypi](https://pypi.org/), and try to follow [semantic
+versioning](https://semver.org/):
+
+> Given a version number MAJOR.MINOR.PATCH, increment the:
+> 1. MAJOR version when you make incompatible API changes
+> 2. MINOR version when you add functionality in a backward compatible manner
+> 3. PATCH version when you make backward compatible bug fixes
+
+When doing a new release, the following steps must be taken:
+1. In a new PR:
+  - Update the string in `version.py`. This will update the value used in
+    `setup.py`. It should be of the format `X.Y.Z`, where `X`, `Y`, `Z` are all
+    integers.
+  - Update all the [binder](https://mybinder.org) links, which are of the form
+    `https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/X.Y.Z?filepath=examples`,
+    which are found in `README.md`, `index.rst`, `examples/README.md`, and some
+    of the tutorial notebooks found in `examples/`. Note that the version tag
+    must match the github tag (specified in the next step) or the link won't
+    work, and this github tag should match the value found in `version.py`.
+2. After merging the above PR into the `main` branch, [create a Github
+   release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)
+   with a new tag matching that used in the binder link above: `X.Y.Z`.
+   Creating the release will trigger the deployment to pypi, via our `deploy`
+   action (found in `.github/workflows/deploy.yml`).
+
+Note that the binder link must match the GitHub tag, but the pypi version is
+based on `version.py`. I have been unable to find a way to link them directly
+(or make [binder](https://mybinder.org) use a `latest` tag, like
+[readthedocs](https://readthedocs.org/) does), so we need to manually ensure
+they match.
+
 ## Testing
 
 Before running tests locally, you'll need

README.md

@@ -1,13 +1,14 @@
 # plenoptic
 
+[![PyPI Version](https://img.shields.io/pypi/v/plenoptic.svg)](https://pypi.org/project/plenoptic/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/LabForComputationalVision/plenoptic/blob/main/LICENSE)
 ![Python version](https://img.shields.io/badge/python-3.7|3.8|3.9|3.10-blue.svg)
 [![Build Status](https://github.com/LabForComputationalVision/plenoptic/workflows/build/badge.svg)](https://github.com/LabForComputationalVision/plenoptic/actions?query=workflow%3Abuild)
 [![Documentation Status](https://readthedocs.org/projects/plenoptic/badge/?version=latest)](https://plenoptic.readthedocs.io/en/latest/?badge=latest)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3995057.svg)](https://doi.org/10.5281/zenodo.3995057)
 [![codecov](https://codecov.io/gh/LabForComputationalVision/plenoptic/branch/main/graph/badge.svg?token=EDtl5kqXKA)](https://codecov.io/gh/LabForComputationalVision/plenoptic)
 [![Tutorials Status](https://github.com/LabForComputationalVision/plenoptic/workflows/tutorials/badge.svg)](https://github.com/LabForComputationalVision/plenoptic/actions?query=workflow%3Atutorials)
-[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/main?filepath=examples)
+[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/1.0.0?filepath=examples)
 
 ![](docs/images/plenoptic_logo_wide.svg)
 
@@ -29,11 +30,10 @@ experiments for further investigation.
 
 ### Installation
 
-The best way to install `plenoptic` is via `pip`. For now, you must do
-this from github directly:
+The best way to install `plenoptic` is via `pip`.
 
 ``` bash
-$ pip install git+https://github.com/LabForComputationalVision/plenoptic.git
+$ pip install plenoptic
 ```
 
 See the [installation

docs/index.rst

@@ -1,3 +1,6 @@
+.. |pypi-shield| image:: https://img.shields.io/pypi/v/plenoptic.svg
+			 :target: https://pypi.org/project/plenoptic/
+
 .. |license-shield| image:: https://img.shields.io/badge/license-MIT-yellow.svg
                     :target: https://github.com/LabForComputationalVision/plenoptic/blob/main/LICENSE
 
@@ -12,6 +15,9 @@
 .. |zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3995057.svg
             :target: https://doi.org/10.5281/zenodo.3995057
 
+.. |binder| image:: https://mybinder.org/badge_logo.svg
+		    :target: https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/1.0.0?filepath=examples
+
 .. plenoptic documentation master file, created by
    sphinx-quickstart on Thu Jun 20 15:56:27 2019.
    You can adapt this file completely to your liking, but it should at least
@@ -21,7 +27,7 @@
 plenoptic
 *********
 
-|license-shield| |python-version-shield| |build| |tutorials| |zenodo|
+|pypi-shield| |license-shield| |python-version-shield| |build| |tutorials| |zenodo| |binder|
 
 .. image:: images/plenoptic_logo_wide.svg
    :align: center
@@ -47,10 +53,9 @@ Installation
 
 .. highlight:: bash
 
-The best way to install ``plenoptic`` is via ``pip``. For now, you must do this
-from github directly::
+The best way to install ``plenoptic`` is via ``pip``.
 
-$ pip install git+https://github.com/LabForComputationalVision/plenoptic.git
+$ pip install plenoptic
 
 See the :ref:`install` page for more details, including how to set up an isolated
 virtual environment (recommended).

docs/install.rst

@@ -14,7 +14,7 @@ installed on your machine, I recommend starting with `miniconda
 
 $ conda create --name plenoptic pip python=3.9
 $ conda activate plenoptic
-$ pip install git+https://github.com/LabForComputationalVision/plenoptic.git
+$ pip install plenoptic
 
 You can also install it directly from source::
 
@@ -46,7 +46,7 @@ Jupyter
 
 If you wish to locally run the notebooks, you will need to install ``jupyter``
 and ``ipywidgets`` (you can also run them in the cloud using `Binder
-<https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/main?filepath=examples>`_).
+<https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/1.0.0?filepath=examples>`_).
 There are two main ways of getting a local `jupyter` install` working with this
 package:
 

examples/02_Eigendistortions.ipynb

@@ -10,7 +10,7 @@
    "source": [
     "# Eigendistortions\n",
     "\n",
-    "**Run notebook online with Binder:**[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/master?filepath=examples/02_Eigendistortions.ipynb)\n",
+    "**Run notebook online with Binder:**[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/1.0.0?filepath=examples/02_Eigendistortions.ipynb)\n",
     "\n",
     "**In this tutorial we will cover:**\n",
     "\n",

examples/04_Perceptual_distance.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# Perceptual distance\n",
     "\n",
-    "**Run notebook online with Binder:** [![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/master?filepath=examples/04_Perceptual_distance.ipynb)\n",
+    "**Run notebook online with Binder:** [![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/1.0.0?filepath=examples/04_Perceptual_distance.ipynb)\n",
     "\n",
     "The easiest way to measure the difference between two images is by computing the mean square error (MSE), but it does not match the perceptual distance judged by humans. Several perceptual distance functions have been developed to better match human perception. This tutorial introduces three perceptual distance functions available in `plenoptic` package: SSIM (structural similarity), MS-SSIM (multiscale structural similarity) and NLPD (normalized Laplacian pyramid distance).\n",
     "\n",

examples/Demo_Eigendistortion.ipynb

@@ -8,7 +8,7 @@
     }
    },
    "source": [
-    "**Run notebook online with Binder:**[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/master?filepath=examples/Demo_Eigendistortion.ipynb)\n",
+    "**Run notebook online with Binder:**[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/1.0.0?filepath=examples/Demo_Eigendistortion.ipynb)\n",
     "\n",
     "# Reproducing Berardino et al., 2017 (Eigendistortions)\n",
     "Author: Lyndon Duong, Jan 2021\n",

examples/README.md

@@ -1,5 +1,5 @@
 # Plenoptic example notebooks
-[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/main?filepath=examples)
+[![Binder](http://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/LabForComputationalVision/plenoptic/1.0.0?filepath=examples)
 
 Browse, preview, and run these notebooks in your browser without installing 
 ``plenoptic.py`` using the ``launch Binder`` button above.

plenoptic/version.py

@@ -1 +1 @@
-version = '0.1.0'
+version = '1.0.0'

setup.py

@@ -18,7 +18,9 @@ def readlines(fn):
 setup(
     name="plenoptic",
     version=VERSION,
-    description="Visual Information Processing",
+    long_description=open('README.md', 'r').read(),
+    long_description_content_type='text/markdown',
+    description="Python library for model-based stimulus synthesis.",
     license="MIT",
     url="https://github.com/LabForComputationalVision/plenoptic",
     author="LabForComputationalVision",