Merge pull request #414 from larrybradley/add-citation

Add citation file

Author: larrybradley

CITATION.rst

@@ -0,0 +1 @@
+See https://github.com/astropy/regions/blob/main/regions/CITATION.rst

MANIFEST.in

@@ -1,4 +1,6 @@
 include CHANGES.rst
+include CITATION.rst
+include regions/CITATION.rst
 include LICENSE.rst
 include README.rst
 include pyproject.toml

README.rst

@@ -15,6 +15,26 @@ instructions
 and usage information.
 
 
+Citing Regions
+--------------
+
+|Zenodo|
+
+If you use Regions for a project that leads to a publication, whether
+directly or as a dependency of another package, please include the
+following acknowledgment::
+
+    This research made use of Regions, an Astropy package for region
+    handling (Bradley et al. 202X).
+
+where (Bradley et al. 202X) is a citation to the `Zenodo
+record <https://doi.org/10.5281/zenodo.5826358>`_ of the
+Regions version that was used. We also encourage citations in
+the main text wherever appropriate. Please see the `CITATION
+<https://github.com/astropy/regions/blob/main/regions/CITATION.rst>`_
+file for details and an example BibTeX entry.
+
+
 License
 -------
 
@@ -36,6 +56,9 @@ for details.
     :target: https://www.astropy.org/
     :alt: Powered by Astropy
 
+.. |Zenodo| image:: https://zenodo.org/badge/35690635.svg
+    :target: https://zenodo.org/badge/latestdoi/35690635
+
 .. |CI Status| image:: https://github.com/astropy/regions/workflows/CI%20Tests/badge.svg#
     :target: https://github.com/astropy/regions/actions
     :alt: CI Status

regions/CITATION.rst

@@ -0,0 +1,51 @@
+Citing Regions
+--------------
+
+If you use Regions for a project that leads to a publication, whether
+directly or as a dependency of another package, please include the
+following acknowledgment:
+
+.. code-block:: text
+
+    This research made use of Regions, an Astropy package for region
+    handling (Bradley et al. 202X).
+
+where (Bradley et al. 202X) is a citation to the `Zenodo record
+<https://doi.org/10.5281/zenodo.5826358>`_ of the Regions version
+that was used. We also encourage citations in the main text wherever
+appropriate.
+
+All Regions versions and citation formats can be found at
+https://doi.org/10.5281/zenodo.5826358. For example, for Regions
+v0.5 one would cite Bradley et al. 2022 with the BibTeX entry
+(https://zenodo.org/record/5826359/export/hx):
+
+.. code-block:: text
+
+    @software{larry_bradley_2022_5826359,
+    author       = {Larry Bradley and
+                    Christoph Deil and
+                    Sushobhana Patra and
+                    Adam Ginsburg and
+                    Thomas Robitaille and
+                    Brigitta Sip{\H o}cz and
+                    Johannes King and
+                    P. L. Lim and
+                    Leo Singer and
+                    Miguel de Val-Borro and
+                    Tim Jenness and
+                    Matthieu Baumann and
+                    Yash-10 and
+                    Axel Donath and
+                    Erik Tollerud and
+                    Jae-Joon Lee and
+                    Katrin Leinweber and
+                    Z\`e Vin{\'{\i}}cius},
+    title        = {astropy/regions: v0.5},
+    month        = jan,
+    year         = 2022,
+    publisher    = {Zenodo},
+    version      = {v0.5},
+    doi          = {10.5281/zenodo.5826359},
+    url          = {https://doi.org/10.5281/zenodo.5826359}
+    }

regions/__init__.py

@@ -14,3 +14,21 @@
 from .io import *  # noqa
 from .shapes import *  # noqa
 from ._utils.examples import *  # noqa
+
+
+# Set the bibtex entry to the article referenced in CITATION.rst.
+def _get_bibtex():
+    import os
+    citation_file = os.path.join(os.path.dirname(__file__), 'CITATION.rst')
+
+    with open(citation_file, 'r') as citation:
+        refs = citation.read().split('@software')[1:]
+        if len(refs) == 0:
+            return ''
+        bibtexreference = f"@software{refs[0]}"
+    return bibtexreference
+
+
+__citation__ = __bibtex__ = _get_bibtex()
+
+del _get_bibtex  # noqa

setup.cfg

@@ -43,7 +43,8 @@ docs =
     sphinx-astropy
 
 [options.package_data]
-regions = data/*
+* = data/*
+regions = CITATION.rst
 regions.shapes.tests = reference/*.txt, data/*.fits
 regions.io.crtf.tests = data/*.crtf
 regions.io.ds9.tests = data/*.reg