From 3733b3355c4242dfba4344bf4351b3e008ff9580 Mon Sep 17 00:00:00 2001
From: Will Barnes <will.t.barnes@gmail.com>
Date: Mon, 26 Aug 2024 11:41:28 -0400
Subject: [PATCH] add citation instructions

---
 docs/citation.rst   |  1 +
 docs/index.rst      |  1 +
 fiasco/CITATION.rst | 37 +++++++++++++++++++++++++++++++++++++
 fiasco/__init__.py  | 37 ++++++++++++++++++++++++++++++++++++-
 4 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 docs/citation.rst
 create mode 100644 fiasco/CITATION.rst

diff --git a/docs/citation.rst b/docs/citation.rst
new file mode 100644
index 00000000..b7cf9094
--- /dev/null
+++ b/docs/citation.rst
@@ -0,0 +1 @@
+.. include:: ../fiasco/CITATION.rst
diff --git a/docs/index.rst b/docs/index.rst
index 7b35d9e1..712cab92 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -55,6 +55,7 @@ In the same way, the `fiasco` package serves up the CHIANTI atomic database.
     generated/gallery/index
     how_to_guides
     topic_guides/index
+    citation
     reference/index
 
 .. _CHIANTI atomic database: http://www.chiantidatabase.org/
diff --git a/fiasco/CITATION.rst b/fiasco/CITATION.rst
new file mode 100644
index 00000000..ccb0edbc
--- /dev/null
+++ b/fiasco/CITATION.rst
@@ -0,0 +1,37 @@
+.. _fiasco-citation:
+
+Citing fiasco
+=============
+
+If you use ``fiasco`` in your scientific work, we would appreciate you citing it in your publications.
+Please add the following line within your methods, conclusion or acknowledgements sections:
+
+*This research used version X.Y.Z (software citation) of the fiasco open source software package.*
+
+The software citation should be the specific `Zenodo DOI`_ for the version used within your work.
+The citation for most current version on Zenodo is,
+
+.. code:: bibtex
+
+   @software{Barnes2024,
+      author       = {Will Barnes and
+                      David Stansby and
+                      Nick Murphy and
+                      Jeffrey Reep and
+                      Laura Hayes and
+                      Stuart Mumford},
+      title        = {wtbarnes/fiasco: v0.2.3},
+      month        = feb,
+      year         = 2024,
+      publisher    = {Zenodo},
+      version      = {v0.2.3},
+      doi          = {10.5281/zenodo.10612118},
+      url          = {https://doi.org/10.5281/zenodo.10612118}
+   }
+
+You can also obtain this information with ``fiasco.__citation__``.
+
+In addition to citing ``fiasco``, you should also cite the CHIANTI atomic database according to the
+`instructions here <https://www.chiantidatabase.org/referencing.html>`__.
+
+.. _Zenodo DOI: https://zenodo.org/records/10612118
diff --git a/fiasco/__init__.py b/fiasco/__init__.py
index 86fbff7d..886643ab 100644
--- a/fiasco/__init__.py
+++ b/fiasco/__init__.py
@@ -20,4 +20,39 @@
 
 log = _init_log()
 
-__all__ = ["IonCollection", "Element", "list_elements", "list_ions", "proton_electron_ratio", "Ion", "Level", "Transitions", "defaults", "log", "__version__"]
+
+def _get_bibtex():
+    import textwrap
+
+    from itertools import compress
+    from pathlib import Path
+
+    # Set the bibtex entry to the article referenced in CITATION.rst
+    citation_file = Path(__file__).parent / "CITATION.rst"
+
+    # Explicitly specify UTF-8 encoding in case the system's default encoding is problematic
+    with Path.open(citation_file, "r", encoding="utf-8") as citation:
+        # Extract the first bibtex block:
+        ref = citation.read().partition(".. code:: bibtex\n\n")[2]
+        lines = ref.split("\n")
+        # Only read the lines which are indented
+        lines = list(compress(lines, [line.startswith("   ") for line in lines]))
+        return textwrap.dedent("\n".join(lines))
+
+
+__citation__ = __bibtex__ = _get_bibtex()
+
+__all__ = [
+    "IonCollection",
+    "Element",
+    "list_elements",
+    "list_ions",
+    "proton_electron_ratio",
+    "Ion",
+    "Level",
+    "Transitions",
+    "defaults",
+    "log",
+    "__version__",
+    "__citation__",
+]