Merge pull request #142 from thewtex/github-actions-for-modules

DOC: Update ITK remote module Python package GitHub Actions docs

Author: thewtex

docs/Build_ITK_Module_Python_packages.rst

@@ -3,14 +3,14 @@ Build ITK Module Python packages
 ======================================
 
 ITK is organized into *modules*. Modules for ITK can be developed outside the
-ITK source tree as *external modules*. The *external module* can be made
+ITK source tree as *remote modules*. The *remote module* can be made
 available in ITK's `CMake <https://www.cmake.org>`_ configuration by
 `contributing it
 <https://github.com/InsightSoftwareConsortium/ITKModuleTemplate#remote-module>`_
-as a *remote module*. Python packages can also be generated for external
+as a *remote module*. Python packages can also be generated for remote
 modules and uploaded to the `Python Package Index (PyPI) <https://pypi.org>`_
 
-This section describes how to create, build, and upload ITK external
+This section describes how to create, build, and upload ITK remote
 module Python packages to PyPI.
 
 
@@ -36,33 +36,84 @@ can be found in the `ITK Software Guide
 GitHub automated CI package builds
 ==================================
 
-Freely available continous integration (CI) testing services for open source
-repositories on `GitHub <https://github.com/>`_ can be used to generate Linux,
+Freely available GitHub Action continous integration (CI) build and test services for open source
+repositories are provided by `GitHub <https://github.com/>`_. These services will build and test the C++ code for your module and also generate Linux,
 macOS, and Windows Python packages for your module.
 
-After enabling builds for the GitHub repository with a `CircleCI
-<https://circleci.com/>`_, `TravisCI <https://travis-ci.org/>`_,
-and `AppVeyor <https://www.appveyor.com/>`_ account, Python wheel
-packages will be available with the continuous integration builds.
-These services use the configurations generated by the `ITKModuleTemplate <https://github.com/InsightSoftwareConsortium/ITKModuleTemplate>`_.
+For every pull request and push to the GitHub repository, a GitHub Action will
+run that builds and runs the repository's C++ tests and reports the results to
+the [ITK CDash Dashboard](https://open.cdash.org/index.php?project=Insight).
+Python packages are also generated for every commit. Packages for a commit's
+build can be downloaded from the GitHub Action result page in the *Artifacts*
+Section.
 
-.. figure:: https://i.imgur.com/OEujGsl.png
-  :alt: CircleCI Python wheels
+.. figure:: images/GitHubActionArtifacts.png
+  :alt: GitHub Action Artifacts
 
-  Linux Python package wheel links can be found in the CircleCI *Artifacts*
-  tab after expanding the available folders.
+Upload the packages to PyPI
+----------------------------
+
+First, `register for an account on PyPI <https://pypi.org>`_.
+
+Next, create a `~/.pypirc` file with your login credentials::
+
+  [distutils]
+  index-servers =
+    pypi
+    pypitest
+
+  [pypi]
+  username=<your-username>
+  password=<your-password>
+
+  [pypitest]
+  repository=https://test.pypi.org/legacy/
+  username=<your-username>
+  password=<your-password>
+
+where `<your-username>` and `<your-password>` correspond to your PyPI account.
+
+Then, upload wheels to the testing server::
+
+  python -m pip install twine
+  python -m twine upload -r pypitest dist/*
+
+Check out the packages on `<https://test.pypi.org/>`_ the testing server.
+
+Finally, upload the wheel packages to the production PyPI server::
+
+  python -m twine upload dist/*
+
+Congratulations! Your packages can be installed with the commands::
+
+  python -m pip install --upgrade pip
+  python -m pip install itk-<yourmodulename>
+
+Automate PyPI Package Uploads
+-----------------------------
+
+Automated uploads of Python packages to the Python package index,
+[PyPI](https://pypi.org) will occur after adding a PyPI upload token to GitHub
+and creating a Git tag.
+
+.. figure:: images/PyPIToken.png
+  :alt: PyPI Token
 
-.. figure:: https://imgur.com/tHMhTII.png
-  :alt: TravisCI Python wheels
+Then, add the API token to the GitHub repository's *Settings -> Secrets* page
+in a key called *pypi_password*. Note that this will be a *token* instead of a
+password. Limit the scope of the token to the individual package as a best
+practice.
 
-  macOS Python package wheels can be downloaded by visiting to the `file.io`
-  link found in the build output. Note: this link may only be valid for the
-  initial download.
+.. figure:: images/GitHubPyPISecret.png
+  :alt: GitHub PyPI token secret
 
-.. figure:: http://imgur.com/Cj5vs3S.png
-  :alt: AppVeyor Python wheels
+To push packages to PyPI, first, make sure to update the `version` for your
+package in the *setup.py* file. Then create a Git tag corresponding to the
+version. A Git tag can be created in the GitHub user interface via
+*Releases -> Draft a new release*.
 
-  Windows Python package wheel links can be found in the AppVeyor *Artifacts* tab.
+.. figure:: images/GitHubReleaseTag.png
+  :alt: GitHub Release Tag
 
 
 Automated platform scripts
@@ -123,43 +174,3 @@ In a PowerShell prompt, run the `windows-build-wheels.ps1` script::
 	PS C:\Windows> cd C:\ITKMyModule
 	PS C:\ITKMyModule> git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage.git IPP
 	PS C:\ITKMyModule> .\ITKPythonPackage\scripts\windows-download-cache-and-build-module-wheels.ps1
-
-
-Upload the packages to PyPI
-===========================
-
-First, `register for an account on PyPI <https://pypi.org>`_.
-
-Next, create a `~/.pypirc` file with your login credentials::
-
-  [distutils]
-  index-servers =
-    pypi
-    pypitest
-
-  [pypi]
-  username=<your-username>
-  password=<your-password>
-
-  [pypitest]
-  repository=https://test.pypi.org/legacy/
-  username=<your-username>
-  password=<your-password>
-
-where `<your-username>` and `<your-password>` correspond to your PyPI account.
-
-Then, upload wheels to the testing server::
-
-  python -m pip install twine
-  python -m twine upload -r pypitest dist/*
-
-Check out the packages on `<https://test.pypi.org/>`_ the testing server.
-
-Finally, upload the wheel packages to the production PyPI server::
-
-  python -m twine upload dist/*
-
-Congratulations! Your packages can be installed with the commands::
-
-  python -m pip install --upgrade pip
-  python -m pip install itk-<yourmodulename>