update release documentation and installation instructions

README.rst

@@ -2,26 +2,7 @@
 Birdy
 =====
 
-.. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
-   :target: http://birdy.readthedocs.io/en/latest/?badge=latest
-   :alt: Documentation Status
-
-.. image:: https://github.com/bird-house/birdy/workflows/build/badge.svg
-    :target: https://github.com/bird-house/birdy/actions
-    :alt: Build Status
-
-.. image:: https://api.codacy.com/project/badge/Grade/da14405a9a6d4c2e9c405d9c0c8babe7
-   :target: https://www.codacy.com/app/cehbrecht/birdy?utm_source=github.com&utm_medium=referral&utm_content=bird-house/birdy&utm_campaign=Badge_Grade
-   :alt: Codacy Code Checks
-
-.. image:: https://img.shields.io/github/license/bird-house/birdy.svg
-   :target: https://github.com/bird-house/birdy/blob/master/LICENSE.txt
-   :alt: GitHub license
-
-.. image:: https://badges.gitter.im/bird-house/birdhouse.svg
-   :target: https://gitter.im/bird-house/birdhouse?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-   :alt: Join the chat at https://gitter.im/bird-house/birdhouse
-
+|PyPI| |Docs| |Build| |Codacy| |License| |Gitter|
 
 Birdy (the bird)
    *Birdy is not a bird but likes to play with them.*
@@ -32,17 +13,45 @@ It is using `OWSLib` from the `GeoPython` project.
 You can try Birdy online using Binder (just click on the binder link below),
 or view the notebooks on NBViewer.
 
-.. image:: https://mybinder.org/badge_logo.svg
-   :target: https://mybinder.org/v2/gh/bird-house/birdy.git/v0.8.3?filepath=notebooks
-   :alt: Binder Launcher
+|Binder|
 
-.. image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg
-   :target: https://nbviewer.jupyter.org/github/bird-house/birdy/tree/v0.8.3/notebooks/
-   :alt: NBViewer
-   :height: 20
+|NBViewer|
 
 Birdy is part of the `Birdhouse`_ project.
 
 Full `documentation <http://birdy.readthedocs.org/en/latest/>`_ is on ReadTheDocs.
 
 .. _Birdhouse: http://bird-house.github.io/en/latest/
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/birdhouse-birdy.svg
+        :target: https://pypi.python.org/pypi/birdhouse-birdy
+        :alt: Python Package Index Build
+
+.. |Docs| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
+        :target: http://birdy.readthedocs.io/en/latest/?badge=latest
+        :alt: Documentation Status
+
+.. |Build| image:: https://github.com/bird-house/birdy/workflows/build/badge.svg
+        :target: https://github.com/bird-house/birdy/actions
+        :alt: Build Status
+
+.. |Codacy| image:: https://api.codacy.com/project/badge/Grade/da14405a9a6d4c2e9c405d9c0c8babe7
+        :target: https://www.codacy.com/app/cehbrecht/birdy?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=bird-house/birdy&amp;utm_campaign=Badge_Grade
+        :alt: Codacy Code Checks
+
+.. |License| image:: https://img.shields.io/github/license/bird-house/birdy.svg
+        :target: https://github.com/bird-house/birdy/blob/master/LICENSE.txt
+        :alt: GitHub license
+
+.. |Gitter| image:: https://badges.gitter.im/bird-house/birdhouse.svg
+        :target: https://gitter.im/bird-house/birdhouse?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+        :alt: Join the chat at https://gitter.im/bird-house/birdhouse
+
+.. |Binder| image:: https://mybinder.org/badge_logo.svg
+        :target: https://mybinder.org/v2/gh/bird-house/birdy.git/v0.8.3?filepath=notebooks
+        :alt: Binder Launcher
+
+.. |NBViewer| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg
+        :target: https://nbviewer.jupyter.org/github/bird-house/birdy/tree/v0.8.3/notebooks/
+        :alt: NBViewer
+        :height: 20

docs/source/development.rst

@@ -12,7 +12,7 @@ Check out code from the birdy GitHub repo and start the installation::
    $ git clone https://github.com/bird-house/birdy.git
    $ cd birdy
    $ conda env create -f environment.yml
-   $ python setup.py develop
+   $ pip install --editable .
 
 Install additional dependencies::
 
@@ -37,7 +37,7 @@ Before committing your changes, we ask that you install `pre-commit` in your env
 `Pre-commit` runs git hooks that ensure that your code resembles that of the project
 and catches and corrects any small errors or inconsistencies when you `git commit`::
 
-     $ conda install -c conda-forge pre_commit
+     $ conda install -c conda-forge pre-commit
      $ pre-commit install
 
 Write Documentation
@@ -63,3 +63,17 @@ Make a new version of Birdy in the following steps:
 See the bumpversion_ documentation for details.
 
 .. _bumpversion: https://pypi.org/project/bumpversion/
+
+Release a new version
+=====================
+
+Leveraging GitHub Workflows, maintainers can release new versions of Birdy automatically:
+
+* Within the repository secrets, set two API tokens (`PYPI_API_TOKEN` and `TEST_PYPI_API_TOKEN`) with push access to Birdy on PyPI and TestPyPI, respectively.
+* Ensure that the changelog and version on the main development branch have been updated to reflect the new version.
+* Create a tag (`vX.Y.Z`) of the main development branch and push to the GitHub repository.
+    * This will trigger a workflow that will attempt to build Birdy and publish it to TestPyPI.
+    * When this actions succeeds, be sure to verify on TestPyPI that the package reflects changes.
+* On GitHub, a maintainer can then publish a new version using the newly created tag.
+    * This will trigger a workflow that will attempt to build Birdy and publish it to PyPI.
+    * Be warned that once published to PyPI, a version number can never be overwritten! Bad versions may only be `yanked <https://pypi.org/help/#yanked>`_.

docs/source/installation.rst

@@ -4,24 +4,23 @@
 Installation
 ************
 
-Install from Anaconda
-=====================
+Install from PyPI
+=================
+
+|pypi|
 
-.. image:: https://anaconda.org/conda-forge/birdy/badges/installer/conda.svg
-   :target: https://anaconda.org/conda-forge/birdy
-   :alt: Ananconda Install
+.. code-block:: console
+
+    $ pip install birdhouse-birdy
 
-.. image:: https://anaconda.org/conda-forge/birdy/badges/version.svg
-   :target: https://anaconda.org/conda-forge/birdy
-   :alt: Anaconda Version
+Install from Anaconda
+=====================
 
-.. image:: https://anaconda.org/conda-forge/birdy/badges/downloads.svg
-   :target: https://anaconda.org/conda-forge/birdy
-   :alt: Anaconda Downloads
+|conda install| |conda version| |conda downloads|
 
 .. code-block:: console
 
-   $ conda install -c conda-forge birdy
+    $ conda install -c conda-forge birdy
 
 Install from GitHub
 ===================
@@ -30,7 +29,24 @@ Check out code from the birdy GitHub repo and start the installation:
 
 .. code-block:: console
 
-   $ git clone https://github.com/bird-house/birdy.git
-   $ cd birdy
-   $ conda env create -f environment.yml
-   $ python setup.py install
+    $ git clone https://github.com/bird-house/birdy.git
+    $ cd birdy
+    $ conda env create -f environment.yml
+    $ python setup.py install
+
+
+.. |pypi| image:: https://img.shields.io/pypi/v/birdhouse-birdy.svg
+        :target: https://pypi.python.org/pypi/birdhouse-birdy
+        :alt: Python Package Index Build
+
+.. |conda install| image:: https://anaconda.org/conda-forge/birdy/badges/installer/conda.svg
+        :target: https://anaconda.org/conda-forge/birdy
+        :alt: Anaconda Install
+
+.. |conda version| image:: https://anaconda.org/conda-forge/birdy/badges/version.svg
+        :target: https://anaconda.org/conda-forge/birdy
+        :alt: Anaconda Version
+
+.. |conda downloads| image:: https://anaconda.org/conda-forge/birdy/badges/downloads.svg
+        :target: https://anaconda.org/conda-forge/birdy
+        :alt: Anaconda Downloads