use setuptools_scm, fix packaging bugs, and update docs

.github/workflows/ci.yaml

@@ -25,7 +25,7 @@ jobs:
           activate-environment: test_env_pyqg # Defined in ci/environment*.yml
           auto-update-conda: false
           python-version: ${{ matrix.python-version }}
-          environment-file: ci/environment-py${{ matrix.python-version }}.yml
+          environment-file: ci/environment-py${{ matrix.python-version }}-pyfftw.yml
           use-only-tar-bz2: true # IMPORTANT: This needs to be set for caching to work properly!
       - name: Set up conda environment
         shell: bash -l {0}
@@ -44,4 +44,4 @@ jobs:
           flags: unittests
           env_vars: OS,PYTHON
           name: codecov-umbrella
-          fail_ci_if_error: false
+          fail_ci_if_error: false

docs/conf.py

@@ -90,9 +90,18 @@ def __getattr__(cls, name):
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+#version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+#release = '0.1'
+# for example take major/minor
+
+try:
+    from importlib.metadata import version
+except ImportError:
+    from importlib_metadata import version
+
+release = version(project)
+version = '.'.join(release.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/development.rst

@@ -125,43 +125,77 @@ install it, check the version, and tear down the virtual environment.
 .. code-block:: bash
 
     $ conda create --yes -n test_env python=3.9 pip nose numpy cython scipy nose
-    $ conda install --yes -n test_env -c nanshe pyfftw
+    $ conda install --yes -n test_env -c conda-forge pyfftw
     $ source activate test_env
     $ pip install pyqg
     $ python -c 'import pyqg; print(pyqg.__version__);'
-    $ source deactivate
+    $ conda deactivate
     $ conda env remove --yes -n test_env
 
 Release Procedure
 =================
 
 Once we are ready for a new release, someone needs to make a pull request which
-updates the version number in setup.py. Also make sure that whats-new.rst in
-the docs is up to date.
+updates `docs/whats-new.rst` in preparation for updating to the new version.
+Then, tag the pull request's merge commit with an updated version tag:
 
-After the new version number PR has been merged, create a new `release`_ in
-github.
+.. code-block:: bash
+
+    $ git remote update
+    $ git checkout master
+    $ git rebase origin/master
+    $ git tag vX.Y.Z # replace X.Y.Z real version, e.g. 0.5.0
+    $ git push origin --tags
 
-The step of publishing to `pypi`_ has to be done manually from the command line.
-(Note: I figured out how this works from these `instructions`_).
-After the new release has been created, do the following.
+Before creating a release or publishing to `pypi`_, however, we'll want to do a
+test release to `testpypi`_ (see instructions there) to ensure the new version
+works:
 
 .. code-block:: bash
 
-    $ cd pyqg
-    $ git fetch upstream
-    $ git checkout master
-    $ git rebease upstream/master
-    # test the release before publishing
-    $ python setup.py register -r pypitest
-    $ python setup.py sdist upload -r pypitest
-    # if that goes well, publish it
-    $ python setup.py register -r pypi
-    $ python setup.py sdist upload -r pypi
+    # Build the new version and upload it to the test version of pypi
+    $ python -m build # could also run `python setup.py sdist`
+    $ twine upload --repository testpypi dist/pyqg-X.Y.Z.tar.gz
+
+As an additional validation, it's worth setting up a test environment and
+ensuring pyqg can be installed:
+
+.. code-block:: bash
+
+    # Create a temporary directory with a fresh conda environment
+    $ mkdir ~/tmp
+    $ cd ~/tmp
+    $ conda create --yes -n test_env python=3.9 pip nose numpy cython scipy nose setuptools setuptools_scm
+    $ source activate test_env
+    $ pip install pyfftw # or install with conda-forge
+
+    # Install the new version of pyqg that we deployed to testpypi
+    $ pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --no-cache-dir pyqg==X.Y.Z
+
+    # Ensure this prints out the test version (X.Y.Z)
+    $ python -c 'import pyqg; print(pyqg.__version__);'
+
+    # Clean up and remove the test environment
+    $ conda deactivate
+    $ conda env remove --yes -n test_env
+
+If this all works, then we're ready to publish to `pypi`_:
+
+.. code-block:: bash
+
+    $ twine upload dist/pyqg-X.Y.Z.tar.gz
 
 Note that pypi will not let you publish the same release twice, so make sure
 you get it right!
 
+In the event that pypi deployment fails (and requires code changes to debug),
+delete the tag, and instead iterate locally using temporary alpha tags (e.g.
+`vX.Y.Z.alpha1`). Push these to testpypi and continue iterating until you can
+successfully install the new version.
+
+Finally, after publishing, you should create a new `release`_ in Github.
+
+.. _testpypi: https://packaging.python.org/en/latest/guides/using-testpypi
 .. _pypi: https://pypi.python.org/pypi/pyqg
 .. _release: https://help.github.com/articles/creating-releases/
 .. _instructions: http://peterdowns.com/posts/first-time-with-pypi.html

docs/environment.yml

@@ -1,12 +1,12 @@
 name: pyqg_test_env
 dependencies:
-  - python=3.6
+  - python=3.9
   - numpy
   - scipy
   - cython
   - pytest
   - future
-  - sphinx<2
+  - sphinx
   - ipython
   - matplotlib
   - numpydoc

docs/installation.rst

@@ -22,8 +22,9 @@ simulations.
 - fftw_ (3.3 or later)
 - pyfftw_ (0.9.2 or later)
 
-If pyqg can't import pyfftw at compile time, it will fall back on numpy_'s fft
-routines.
+If pyqg can't import pyfftw at compile time, it can fall back on numpy_'s fft
+routines. **Note that the numpy_ fallback requires a local install (see
+[below](#installing-pyqg)).**
 
 PyQG can also conveniently store model output data as an xarray dataset. The feature (which is used in some of the examples in this documentation) requires xarray_.
 
@@ -86,12 +87,9 @@ the pyfftw conda package was created. There are currently 13
 `pyfftw user packages <https://anaconda.org/search?q=pyfftw>`__
 hosted on anaconda.org. Each has different dependencies and platform support
 (e.g. linux, windows, mac.)
-The `nanshe <https://anaconda.org/nanshe/pyfftw>`__ channel version is the most
-popular and appears to have the broadest cross-platform support. We don't know
-who nanshe is, but we are greatful to him/her.
-
-To install pyfftw from the `conda-forge <https://conda-forge.github.io/>`_
-channel, open a terminal and run the command
+The `conda-forge <https://anaconda.org/conda-forge/pyfftw>`__ version is the
+most popular and appears to have the broadest cross-platform support. To
+install it, open a terminal and run the command
 
 .. code-block:: bash
 
@@ -226,31 +224,26 @@ use the latest development version.
 
     $ git clone https://github.com/pyqg/pyqg.git
 
-Then install pyqg on your system:
-
-.. code-block:: bash
-
-    $ python setup.py install [--user]
-
-(The ``--user`` flag is optional--use it if you don't have root privileges.)
-
-If you want to make changes in the code, set up the development mode:
+Then install pyqg locally on your system:
 
 .. code-block:: bash
 
-    $ python setup.py develop
+    $ cd pyqg && pip install --editable .
 
-pyqg is a work in progress, and we really encourage users to contribute to its
+This will also allow you to make and test changes to the library.  pyqg is a
+work in progress, and we really encourage users to contribute to its
 :doc:`/development`
 
+**Note that due to Cython build considerations, this local install method is
+required if you do not wish to use pyfftw.**
 
 .. _advanced-install:
 
 Installing with OpenMP support on OSX
 -------------------------------------
 
-There are two options for installing on OSX with OpenMP support.  Both methods require using the Anaconda distribution of
-Python.
+There are two options for installing on OSX with OpenMP support.  Both methods
+require using the Anaconda distribution of Python.
 
 1. Using Homebrew
 

pyproject.toml

@@ -0,0 +1,10 @@
+[build-system]
+requires = [
+    "importlib_metadata",
+    "setuptools>=45",
+    "setuptools_scm[toml]>=6.2",
+    "wheel",
+    "cython",
+    "pyfftw",
+    "oldest-supported-numpy"
+]

pyqg/__init__.py

@@ -6,6 +6,13 @@
 from .layered_model import LayeredModel
 from .particles import LagrangianParticleArray2D, GriddedLagrangianParticleArray2D
 
-from ._version import get_versions
-__version__ = get_versions()['version']
-del get_versions
+try:
+    from importlib.metadata import version, PackageNotFoundError
+except ImportError:
+    from importlib_metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("pyqg")
+except PackageNotFoundError:
+    # package is not installed
+    pass