Merge branch 'ckhrulev/citing-pism' into dev

pism · Jul 11, 2024 · bcd7aef · bcd7aef
2 parents fd4b413 + e7db308
commit bcd7aef
Show file tree

Hide file tree

Showing 19 changed files with 338 additions and 225 deletions.
diff --git a/ACKNOWLEDGE.rst b/ACKNOWLEDGE.rst
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -11,6 +11,10 @@ Changes since v2.1
 - Update some examples in `examples/marine`.
 - Fix an bug reported by Ken Mankoff: scripts in `examples/antarctica/` required PISM
   built with PROJ.
+- Add a section about citing PISM to the manual; remove redundant and possibly
+  inconsistent recommendations elsewhere in PISM's docs.
+- Add a section about publishing PISM results to the manual. This section covers archiving
+  the code, model inputs and outputs, etc.
 
 Changes since v2.0
 ==================

diff --git a/CITATION.cff b/CITATION.cff
@@ -73,7 +73,10 @@
 
 cff-version: 1.2.0
 title: 'Parallel Ice Sheet Model (PISM)'
-message: "If you use this software, please cite it using the metadata from this file."
+message: Please see PISM's manual https://www.pism.io/docs/citing for citation guidelines.
+
+  If the manual is not available, please refer to the file doc/sphinx/citing/index.rst in
+  the PISM repository.
 type: software
 doi: 10.5281/zenodo.1199019
 contact:

diff --git a/README.rst b/README.rst
@@ -21,8 +21,9 @@ PISM is jointly developed at the `University of Alaska, Fairbanks (UAF) <uaf_>`_
 `Potsdam Institute for Climate Impact Research (PIK) <pik_>`_. UAF developers are based in
 the `Snow, Ice, and Permafrost Group <sip_>`_ at the `Geophysical Institute <gi_>`_.
 
-Please see ``ACKNOWLEDGE.rst`` and ``doc/funding.csv`` for how to acknowledge the use of PISM
-and a list of grants supporting PISM development.
+Please see PISM's manual https://www.pism.io/docs/citing for how to acknowledge the use of
+PISM and PISM's funding sources. If the manual is not available, please refer to the file
+``doc/sphinx/citing/index.rst`` in the PISM repository.
 
 Homepage
 --------
@@ -62,14 +63,11 @@ Want to contribute? Great! See `Contributing to PISM <pism-contributing_>`_.
 .. _pism-contributing: http://www.pism.io/docs/contributing
 .. _pism-installation: http://www.pism.io/docs/installation
 .. _mpi: http://www.mcs.anl.gov/research/projects/mpi/
-.. _petsc: http://www.mcs.anl.gov/petsc/
+.. _petsc: https://petsc.org/
 .. _cf: http://cf-pcmdi.llnl.gov/
 .. _netcdf: http://www.unidata.ucar.edu/software/netcdf/
 .. _sip: https://www.gi.alaska.edu/research/snow-ice-and-permafrost
 .. _gi: http://www.gi.alaska.edu
-.. _NASA-MAP: http://map.nasa.gov/
-.. _NASA-Cryosphere: http://ice.nasa.gov/
-.. _NSF-Polar: https://nsf.gov/geo/plr/about.jsp
 .. _Slack-PISM: https://uaf-pism.slack.com/join/shared_invite/enQtODc3Njc1ODg0ODM5LThmOTEyNjEwN2I3ZTU4YTc5OGFhNGMzOWQ1ZmUzMWUwZDAyMzRlMzBhZDg1NDY5MmQ1YWFjNDU4MDZiNTk3YmE
 .. _uaf-pism: mailto:uaf-pism@alaska.edu
 

diff --git a/doc/Makefile b/doc/Makefile
@@ -1,3 +1,2 @@
-update_funding:
-	python3 ./acknowledge.py > ../ACKNOWLEDGE.rst
-	python3 ./acknowledge.py --manual > sphinx/funding.txt
+sphinx/funding.txt: ./funding.py funding.csv
+	python3 ./funding.py > $@
diff --git a/doc/acknowledge.py b/doc/acknowledge.py
diff --git a/doc/citing-pism.bib b/doc/citing-pism.bib
diff --git a/doc/funding.py b/doc/funding.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+
+import csv
+import time
+
+year = time.gmtime(time.time())[0]
+
+funding = {}
+with open("funding.csv", "r") as f:
+    reader = csv.reader(f, skipinitialspace=True, quoting=csv.QUOTE_ALL)
+
+    funding = {}
+    for row in reader:
+        start_year, end_year, agency, number, _ = row
+
+        try:
+            start_year = int(start_year)
+            end_year = int(end_year)
+        except:
+            continue
+
+        # skip grants for which we don't have a number (yet)
+        if number.strip() == "":
+            continue
+
+        if start_year <= year and year <= end_year:
+            try:
+                funding[agency].append(number)
+            except:
+                funding[agency] = [number]
+
+def join(strings):
+    assert len(strings) > 0
+    if len(strings) == 1:
+        return strings[0]
+    elif len(strings) == 2:
+        return "{} and {}".format(strings[0], strings[1])
+    else:
+        return join(["{}, {}".format(strings[0], strings[1]),
+                     join(strings[2:])])
+
+grants = []
+for k, v in funding.items():
+    suffix = "s" if len(v) > 1 else ""
+
+    grants.append("{agency} grant{suffix} {number}".format(agency=k,
+                                                           suffix=suffix,
+                                                           number=join(v)))
+
+print("""
+..
+   DO NOT EDIT: This file was automatically generated by running doc/funding.py
+
+   Edit doc/funding.py and doc/funding.csv instead.
+""")
+
+print("""
+Development of PISM is supported by {grants}.""".format(grants=join(grants)))
diff --git a/doc/ice-bib.bib b/doc/ice-bib.bib
@@ -1,3 +1,16 @@
+@Article{Katz2021,
+  author    = {Katz, Daniel S. and Chue Hong, Neil P. and Clark, Tim and Muench, August and Stall, Shelley and Bouquin, Daina and Cannon, Matthew and Edmunds, Scott and Faez, Telli and Feeney, Patricia and Fenner, Martin and Friedman, Michael and Grenier, Gerry and Harrison, Melissa and Heber, Joerg and Leary, Adam and MacCallum, Catriona and Murray, Hollydawn and Pastrana, Erika and Perry, Katherine and Schuster, Douglas and Stockhause, Martina and Yeston, Jake},
+  journal   = {F1000Research},
+  title     = {Recognizing the value of software: a software citation guide},
+  year      = {2021},
+  issn      = {2046-1402},
+  month     = jan,
+  pages     = {1257},
+  volume    = {9},
+  doi       = {10.12688/f1000research.26932.2},
+  publisher = {F1000 Research Ltd},
+}
+
 @Article{Garbe2023,
   author    = {Julius Garbe and Maria Zeitz and Uta Krebs-Kanzow and Ricarda Winkelmann},
   journal   = {The Cryosphere},

diff --git a/doc/sphinx/acknowledgments.rst b/doc/sphinx/acknowledgments.rst
@@ -4,6 +4,8 @@
 
 .. include:: <isonum.txt>
 
+.. _sec-acknowledgments:
+
 Acknowledgments
 ===============
 

diff --git a/doc/sphinx/authorship.py b/doc/sphinx/authorship.py
@@ -14,7 +14,7 @@
 Authorship
 ==========
 
-   *Copyright* |copy| *2004 -- 2023 the PISM authors.*
+   *Copyright* |copy| *2004 -- 2024 the PISM authors.*
 
    *This file is part of PISM. PISM is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as published by the Free

diff --git a/doc/sphinx/authorship.rst b/doc/sphinx/authorship.rst
@@ -9,7 +9,7 @@
 Authorship
 ==========
 
-   *Copyright* |copy| *2004 -- 2023 the PISM authors.*
+   *Copyright* |copy| *2004 -- 2024 the PISM authors.*
 
    *This file is part of PISM. PISM is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License as published by the Free