pydeck: Add Makefile to simplify publishing

bindings/pydeck/Makefile

@@ -0,0 +1,49 @@
+init:
+	# Build deck.gl at the root of this repository
+	cd ../..; yarn bootstrap; cd -; \
+	# Set up the pydeck project
+	pip install -r requirements.txt
+	pip install -r requirements-dev.txt
+	pip install -e .
+	$(MAKE) prepare-jupyter
+
+prepare-jupyter:
+	# Enable the notebook extension
+	jupyter nbextension install --sys-prefix --symlink --overwrite --py pydeck
+	jupyter nbextension enable --sys-prefix --py pydeck
+	# Build and install the JS module
+	cd ../../modules/jupyter-widget/; \
+	  jupyter labextension install @jupyter-widgets/jupyterlab-manager --no-build; \
+	  jupyter labextension install . --no-build; \
+	  jupyter labextension link .; \
+	  jupyter lab build; \
+	  cd ../../bindings/pydeck
+
+test:
+	pytest
+
+docs:
+	cd docs; \
+	$(MAKE) html
+
+publish-conda:	
+	echo "NOTE pydeck does not yet publish to conda-forge. Awaiting #4202."
+
+bump-version:
+	@read -p "Choose a release type {MAJOR, MINOR, PATCH, BETA, ALPHA, RC}:" choice; \
+	python bump_version.py "$$choice";
+
+publish-pypi:
+	rm -rf ./dist/*
+	pip install .
+	python setup.py sdist bdist_wheel
+	pip install twine
+	python -m twine upload dist/*
+
+bump-and-publish:
+	$(MAKE) bump-version;
+	$(MAKE) test;
+	VERSION=$$(python -c "import pydeck; print(pydeck.__version__)");
+	git commit -am "Release version $$VERSION";
+	$(MAKE) publish-conda;
+	$(MAKE) publish-pypi;

bindings/pydeck/PUBLISH.md

@@ -1,14 +1,20 @@
 Publication checklist for pydeck
 ==========
 
-Preferably run these commands in a virtual environment. Install pydeck from its source.
-Build deck.gl from its source as well. If you're unsure how to do this, the README.md files for both.
-This also assumes that you have pypi credentials to publish pydeck and NPM credentials to publish @deck.gl/juypter-widget.
+### Notes before publication
 
-1) Verify that there is a CDN-hosted release of @deck.gl/jupyter-widget for the standalone html template
-within pydeck.
+- Run these commands in a virtual environment.
+- Build deck.gl from its source.
+- Install pydeck from its source.
+- This checklist also assumes that you have PyPI credentials to publish pydeck
+and valid NPM credentials to publish @deck.gl/juypter-widget.
+- Verify that there is a CDN-hosted release of @deck.gl/jupyter-widget for the standalone html template
+within pydeck accessible on [JSDelivr](https://www.jsdelivr.com/package/npm/@deck.gl/jupyter-widget).
+- Optional but encouraged: Check that the build works on test.pypi. See *Producing a test release* below.
 
-2) Verify that Deck object works on a fresh install from the source in the following
+### Producing a production release
+
+1) Verify that Deck object works on a fresh install from the source in the following
 environments:
 
 - `.show()` in a Jupyter Notebook
@@ -17,9 +23,22 @@ environments:
 - `.to_html()` in Jupyter Lab
 - `.to_html()` in a Python REPL
 
-3) Bump the version number in `pydeck/_version.py`
+2) Run `make bump-and-publish` and select the kind of release at the prompt.
+This will run Python and JS tests and produce a commit with the release version.
+
+3) Verify that your publications are successful:
+
+- https://pypi.org/project/pydeck/
+- Conda-forge URL TBD
+
+4) Inform the deck.gl Slack channel that a new version of pydeck has been published.
+
+
+### Producing a test release
+
+1) Run `python bump_version.py -h` to bump the version programmatically.
 
-4) Run the following commands to publish to the test.pypi environment:
+2) Run the following commands to publish to the test.pypi environment:
 
 ```
 rm -r ./dist/*  # If exists, clear out the current dist folder
@@ -29,38 +48,31 @@ pip install twine  # If you have not installed twine
 python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
 ```
 
-5) In a fresh virtualenv, install pydeck from test.pypi:
+3) In a fresh virtualenv, you can install pydeck from test.pypi:
 
 ```
 pip install -i https://test.pypi.org/simple/ pydeck=={{version}}
 ```
 
 where `{{version}}` is your semantic version.
 
-6) Verify that pydeck works from test.pypi in the same environments as above.
+4)  Verify that pydeck works from test.pypi in the same environments as above.
 
-7) If everything appears to be working, publish to pypi.
+5) If everything appears to be working, you can publish to PyPI and conda-forge.
 
-```
-twine upload dist/*
-```
-
-8) Verify again the pydeck installed from the main pypi works in the environment above.
-
-9) Inform the deck.gl Slack channel that a new version of pydeck has been published.
 
-
-Updating documentation
-==========
+## Updating documentation
 
 The pydeck documentation has three main components
 
 - The .md files in the pydeck directory.
 - The .rst files in the pydeck directory under `docs/`.
-- The binder examples, which are kept on the `binder` branch of this repository.
+- The Binder examples, which are kept on the `binder` branch of this repository.
 - Most critically, the docstrings in the Python code itself, which combined with the .rst files generates
 the documentation at https://deckgl.readthedocs.io/en/latest/.
 
+The documentation is currently build manually at the [readthedocs](https://readthedocs.org/projects/deckgl/) admin page.
+
 ### Updating the binder branch
 
 Align the binder branch in-line with what's on master:
@@ -73,7 +85,7 @@ git merge binder
 git push
 ```
 
-The Dockerfile at the root of the deck.gl repository can be tested locally with the following code:
+The Dockerfile at the root of the deck.gl repository on the binder branch can be tested locally with the following code:
 
 ```bash
 docker build -t test-binder:latest .

bindings/pydeck/README.md

@@ -96,7 +96,7 @@ Error handling will be expanded in future versions of pydeck.
 ### Issues
 
 If you encounter an issue, file it in the [deck.gl issues page](https://github.com/uber/deck.gl/issues/new?assignees=&labels=question&template=question.md&title=)
-and include your console output, if any.
+and include your browser's console output, if any.
 
 
 ### Installation from source
@@ -111,55 +111,25 @@ cd deck.gl/bindings/pydeck
 # Create a virtual environment
 python3 -m venv env3
 . env3/bin/activate
-
-python3 setup.py install
 ```
 
 ## Development
 
-Build the deck.gl project at the root of this repository:
+From the directory of this README, set up the developer environment for pydeck:
 
 ```bash
-git clone https://github.com/uber/deck.gl/
-cd deck.gl
-# Build the entire deck.gl project
-yarn bootstrap
+make init
 ```
 
-From the directory of this README, build pydeck:
-
-```bash
-# Create a virtual environment
-python3 -m venv env3
-. env3/bin/activate
-
-pip install -r requirements.txt
-pip install -r requirements-dev.txt
-pip install -e .
-```
+Development inside a virtual environment is preferred.
 
 JupyterLab is the recommended environment for development testing with pydeck.
-To develop with JupyterLab, run from this directory:
-
-```bash
-# cd ../../modules/jupyter-widget
-jupyter labextension install @jupyter-widgets/jupyterlab-manager --no-build
-jupyter labextension install . --no-build
-jupyter labextension link .
-cd -
-jupyter lab build
-```
-
 The `jupyter lab --watch` command can be used to provide hot reloading for development.
 
-
 ### Tests
 
 Tests are handled by pytest. In the top-level pydeck directory, you can type:
 
 ```bash
 pytest
 ```
-
-Tests expect the development build of pydeck, specified above.
-Click on the URLs in the test output to see visualizations generated by the tests.

bindings/pydeck/bump_version.py

@@ -0,0 +1,62 @@
+import argparse
+import sys
+
+import semver
+import jinja2
+
+from pydeck._version import __version__
+
+RELEASE_TYPES = ["MAJOR", "MINOR", "PATCH", "BETA", "ALPHA", "RC"]
+
+
+def bump(release_type):
+    version_info = semver.parse_version_info(__version__)
+    if release_type == "MAJOR":
+        return version_info.bump_major()
+    elif release_type == "MINOR":
+        return version_info.bump_minor()
+    elif release_type == "PATCH":
+        return version_info.bump_patch()
+    elif release_type == "ALPHA":
+        return version_info.bump_prerelease(token="a")
+    elif release_type == "BETA":
+        return version_info.bump_prerelease(token="b")
+    elif release_type == "RC":
+        return version_info.bump_prerelease(token="rc")
+    else:
+        raise Exception(
+            "Release type must be one of the following:", ", ".join(RELEASE_TYPES)
+        )
+
+
+def rewrite_version_file(semver):
+    with open("pydeck/_version.py", "w+") as f:
+        t = jinja2.Template("__version__ = '{{semver_str}}'")
+        contents = t.render(semver_str=str(semver))
+        f.write(contents)
+
+
+parser = argparse.ArgumentParser(
+    description="Bump semver for pydeck. Modifies pydeck/_version.py directly."
+)
+parser.add_argument(
+    "release_type", action="store", choices=RELEASE_TYPES, help="Release type to bump"
+)
+parser.add_argument(
+    "-y", "--yes", action="store_true", dest="yes", help="Automatically answer yes"
+)
+
+
+if __name__ == "__main__":
+    args = parser.parse_args()
+    should_accept_bump = args.yes
+    bumped_version = bump(args.release_type)
+    inform_bump = "Raising pydeck {} to {}".format(__version__, str(bumped_version))
+    print(inform_bump)
+    if not should_accept_bump:
+        prompt = "Proceed? (Y/n) "
+        response = input(prompt)
+        if response != "Y":
+            sys.exit(0)
+    rewrite_version_file(bumped_version)
+    print(bumped_version)

bindings/pydeck/pydeck/_version.py

@@ -1,6 +1 @@
-#!/usr/bin/env python
-
-# Copyright (c) Uber Technologies, Inc.
-# Distributed under the terms of the Modified BSD License.
-version_info = (0, 2, 1)
-__version__ = '.'.join(map(str, version_info))
+__version__ = "0.2.1"

bindings/pydeck/requirements-dev.txt

@@ -13,3 +13,4 @@ requests
 sphinx
 recommonmark
 jupyterlab
+semver