add citation instructions

docs/citation.rst

@@ -0,0 +1 @@
+.. include:: ../fiasco/CITATION.rst

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/

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

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__",
+]