Merge pull request #85 from pkgw/add-doi

Add support for automated Zenodo deposition and DOI registration

ci/azure-deployment.yml

@@ -85,3 +85,24 @@ jobs:
       displayName: Publish PyPI releases
       env:
         PYPI_TOKEN: $(PYPI_TOKEN)
+
+  - job: zenodo_publish
+    pool:
+      vmImage: ubuntu-20.04
+    variables:
+    - group: Deployment Credentials
+
+    steps:
+    - template: azure-job-setup.yml
+      parameters:
+        setupCranko: true
+
+    - bash: cranko zenodo upload-artifacts --metadata=ci/zenodo.json5 $BASH_WORKSPACE/sdist/*.tar.gz
+      displayName: Upload source tarball
+      env:
+        ZENODO_TOKEN: $(ZENODO_TOKEN)
+
+    - bash: cranko zenodo publish --metadata=ci/zenodo.json5
+      displayName: Publish to Zenodo
+      env:
+        ZENODO_TOKEN: $(ZENODO_TOKEN)

ci/azure-sdist.yml

@@ -9,6 +9,13 @@ jobs:
   pool:
     vmImage: ubuntu-20.04
 
+  # Need Zenodo credentials to generate DOIs during formal releases. But make
+  # sure not to provide credentials otherwise (although Azure has its own checks
+  # to not provide secrets during PR builds).
+  ${{ if and(eq(variables['Build.SourceBranchName'], 'rc'), ne(variables['build.reason'], 'PullRequest')) }}:
+    variables:
+    - group: Deployment Credentials
+
   steps:
 
   - checkout: self
@@ -21,14 +28,24 @@ jobs:
       echo "##vso[task.prependpath]$d"
     displayName: Install latest Cranko
 
+  - bash: cranko release-workflow apply-versions
+    displayName: Apply Cranko versions
+
+  - bash: |
+      cranko zenodo preregister --metadata=ci/zenodo.json5 toasty toasty/cli.py CHANGELOG.md
+    displayName: "Preregister Zenodo DOI"
+    ${{ if and(eq(variables['Build.SourceBranchName'], 'rc'), ne(variables['build.reason'], 'PullRequest')) }}:
+      env:
+          ZENODO_TOKEN: $(ZENODO_TOKEN)
+
   - bash: |
       set -xeuo pipefail
-      cranko release-workflow apply-versions
       git add .
       cranko release-workflow commit
-      git show HEAD
+      git show
     displayName: Make release commit
 
+
   - bash: |
       artifact_dir="$(Build.ArtifactStagingDirectory)/git-release"
       mkdir -p "$artifact_dir"

ci/zenodo.json5

@@ -0,0 +1,69 @@
+// See https://pkgw.github.io/cranko/book/latest/integrations/zenodo.html
+// and https://developers.zenodo.org/#representation
+
+{
+  conceptrecid: 'new-for:0.18.0',
+
+  metadata: {
+    upload_type: 'software',
+    language: 'eng',
+
+    // ** Keep this alphabetical by family name!!! **
+    creators: [
+      {
+        affiliation: 'Google',
+        name: 'Beaumont, Christopher',
+      },
+      {
+        affiliation: 'Space Telescope Science Institute; SUPA, School of Physics and Astronomy, University of St. Andrews',
+        name: 'Brasseur, C.',
+        orcid: '0000-0002-9314-960X',
+      },
+      {
+        affiliation: 'Winter Way',
+        name: 'Norman, Henrik',
+        orcid: '0000-0003-4189-3450',
+      },
+      {
+        affiliation: 'Aperio Software',
+        name: 'Robitaille, Thomas P.',
+        orcid: '0000-0002-8642-1329',
+      },
+      {
+        affiliation: 'Center for Astrophysics | Harvard & Smithsonian',
+        name: 'Williams, Peter K. G.',
+        orcid: '0000-0003-3734-3587',
+      },
+      {
+        affiliation: 'US Space and Rocket Center',
+        name: 'Weigel, A. David',
+        orcid: '0000-0002-8026-2291',
+      },
+    ],
+
+    // Subset of HTML allowed here:
+    description: 'toasty is a Python library that helps you create “tile pyramids” \
+from astronomical image data, as used in the TOAST format. These multi-resolution \
+maps can be viewed in software such as the AAS WorldWide Telescope. Learn more \
+at <a href="https://toasty.readthedocs.io/">the toasty website</a>.',
+
+    access_right: 'open',
+    license: 'MIT', // see https://spdx.org/licenses/
+
+    // Relevant grants are currently (2022 Aug) missing from Zenodo's database
+    // so we don't include them for now.
+    //
+    // grants: [
+    //   // National Science Foundation:
+    //   {id: '10.13039/100000001::2004840'},
+    // ],
+
+    // Keywords use an uncontrolled vocabulary (and so are of limited usefulness):
+    keywords: [
+      'AAS WorldWide Telescope',
+      'Astronomy',
+      'Python',
+      'Visualization',
+    ],
+  },
+}

docs/cli.rst

@@ -15,6 +15,9 @@ CLI Reference
    cli/pipeline-process-todos
    cli/pipeline-publish
    cli/pipeline-refresh
+   cli/show-concept-doi
+   cli/show-version
+   cli/show-version-doi
    cli/tile-allsky
    cli/tile-healpix
    cli/tile-study

docs/cli/show-concept-doi.rst

@@ -0,0 +1,33 @@
+.. _cli-show-concept-doi:
+
+===========================
+``toasty show concept-doi``
+===========================
+
+The ``show concept-doi`` command prints the `concept DOI`_ associated with
+the Toasty software package.
+
+.. _concept DOI: https://help.zenodo.org/
+
+Usage
+=====
+
+.. code-block:: shell
+
+   toasty show concept-doi
+
+Prints out Toasty’s concept DOI.
+
+Notes
+=====
+
+A `concept DOI`_ is a unique identifier used to associate multiple releases of a
+software package. If you are trying to preserve information about your usage of
+the Toasty software, you should almost certainly prefer the
+:ref:`cli-show-version-doi` command.
+
+
+See Also
+========
+
+- :ref:`cli-show-version-doi`

docs/cli/show-version-doi.rst

@@ -0,0 +1,39 @@
+.. _cli-show-version-doi:
+
+===========================
+``toasty show version-doi``
+===========================
+
+The ``show version-doi`` command prints the `DOI`_ associated with
+the current version of the Toasty software package.
+
+.. _DOI: https://help.zenodo.org/
+
+Usage
+=====
+
+.. code-block:: shell
+
+   toasty show version-doi
+
+Prints out the DOI of the current version of Toasty.
+
+Notes
+=====
+
+While the version DOI in and of itself does not provide any information that
+isn’t already provided more clearly by the :ref:`cli-show-version` command, the
+version DOI can be used to properly cite your use of the Toasty software in an
+academic context.
+
+While each release of Toasty has its own version DOI, all releases of toasty
+share the same “concept DOI”, which can be obtained with the
+:ref:`cli-show-concept-doi` command. Unless you specifically know that you need the
+concept DOI for a particular application, you should use the version DOI.
+
+
+See Also
+========
+
+- :ref:`cli-show-concept-doi`
+- :ref:`cli-show-version`

docs/cli/show-version.rst

@@ -0,0 +1,34 @@
+.. _cli-show-version:
+
+=======================
+``toasty show version``
+=======================
+
+The ``show version`` command prints out the current version of the Toasty
+software package.
+
+.. _DOI: https://help.zenodo.org/
+
+Usage
+=====
+
+.. code-block:: shell
+
+   toasty show version
+
+Prints out the current version of Toasty.
+
+Notes
+=====
+
+In academic contexts, you may also wish to use the :ref:`cli-show-version-doi`
+command to obtain a `DOI`_ that can be used to properly cite your use of the
+Toasty software.
+
+.. _DOI: https://help.zenodo.org/
+
+
+See Also
+========
+
+- :ref:`cli-show-version-doi`

pyproject.toml

@@ -8,6 +8,7 @@ requires = [
 build-backend = 'setuptools.build_meta'
 
 [tool.cranko]
-extra_python_rewrite_files = [
-  "docs/conf.py"
+annotated_files = [
+  "docs/conf.py",
+  "toasty/cli.py",
 ]

toasty/cli.py

@@ -226,6 +226,41 @@ def make_thumbnail_impl(settings):
         thumb.save(f, format="JPEG")
 
 
+# "show" subcommand
+
+
+def show_getparser(parser):
+    subparsers = parser.add_subparsers(dest="show_command")
+    _parser = subparsers.add_parser("concept-doi")
+    _parser = subparsers.add_parser("version")
+    _parser = subparsers.add_parser("version-doi")
+
+
+def show_impl(settings):
+    if settings.show_command is None:
+        print('Run the "show" command with `--help` for help on its subcommands')
+        return
+
+    if settings.show_command == "concept-doi":
+        # This string constant will be rewritten by Cranko during releases:
+        doi = "xx.xxxx/dev-build.toasty.concept"
+        if not doi.startswith("10."):
+            warn("this DOI is a fake value used for development builds")
+        print(doi)
+    elif settings.show_command == "version":
+        # This string constant will be rewritten by Cranko during releases:
+        version = "0.dev0"  # cranko project-version
+        print(version)
+    elif settings.show_command == "version-doi":
+        # This string constant will be rewritten by Cranko during releases:
+        doi = "xx.xxxx/dev-build.toasty.version"
+        if not doi.startswith("10."):
+            warn("this DOI is a fake value used for development builds")
+        print(doi)
+    else:
+        die('unrecognized "show" subcommand ' + settings.show_command)
+
+
 # "tile_allsky" subcommand
 
 

toasty/tests/test_misc.py

@@ -15,10 +15,12 @@
 class TestMiscCli(object):
     def setup_method(self, method):
         from tempfile import mkdtemp
+
         self.work_dir = mkdtemp()
 
     def teardown_method(self, method):
         from shutil import rmtree
+
         rmtree(self.work_dir)
 
     def work_path(self, *pieces):
@@ -29,9 +31,9 @@ def test_make_thumbnail(self):
         Just a smoketest.
         """
         args = [
-            'make-thumbnail',
-            test_path('Equirectangular_projection_SW-tweaked.jpg'),
-            self.work_path('basic_cli'),
+            "make-thumbnail",
+            test_path("Equirectangular_projection_SW-tweaked.jpg"),
+            self.work_path("basic_cli"),
         ]
         cli.entrypoint(args)
 
@@ -43,10 +45,28 @@ def test_crop(self):
 
         parser = argparse.ArgumentParser()
         ImageLoader.add_arguments(parser)
-        settings = parser.parse_args(['--crop=1,2,3,4'])
-        img = ImageLoader.create_from_args(settings).load_path(test_path('crop_input.png'))
+        settings = parser.parse_args(["--crop=1,2,3,4"])
+        img = ImageLoader.create_from_args(settings).load_path(
+            test_path("crop_input.png")
+        )
         arr = img.asarray()
         assert arr.shape == (256, 256, 3)
         assert arr.max() == 0
 
+    def test_show_concept_doi(self):
+        """
+        More smoketests.
+        """
+        cli.entrypoint(["show", "concept-doi"])
 
+    def test_show_version(self):
+        """
+        More smoketests.
+        """
+        cli.entrypoint(["show", "version"])
+
+    def test_show_version_doi(self):
+        """
+        More smoketests.
+        """
+        cli.entrypoint(["show", "version-doi"])