add a CITATION.md and a citing page to the docs (#1731)

Co-authored-by: Eric T. Johnson <[email protected]>

CITATION.md

@@ -0,0 +1,2 @@
+If you use AMReX-Astro Microphysics, please cite the Zenodo DOI.
+The latest version is always here: https://doi.org/10.5281/zenodo.2620544

Docs/Makefile

@@ -21,6 +21,7 @@ clean:
 
 html:
 	./rp.py > source/runtime_parameters.rst
+	curl -L -H 'Accept: application/x-bibtex' https://zenodo.org/api/records/2620544 > source/zenodo.bibtex.txt
 	doxygen Doxyfile
 	breathe-apidoc --o source doxy_files/xml
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Docs/source/citing.rst

@@ -0,0 +1,9 @@
+Citing Microphysics
+===================
+
+.. mdinclude:: ../../CITATION.md
+
+The bibtex for the latest version is included below (updated automatically):
+
+.. literalinclude:: ./zenodo.bibtex.txt
+   :language: bibtex

Docs/source/conf.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 #
 # Microphysics documentation build configuration file, created by
 # sphinx-quickstart on Tue Oct 23 11:59:54 2018.
@@ -23,16 +22,14 @@
 import subprocess
 import sys
 
-import breathe
 
 sys.path.insert(0, os.path.abspath('.'))
 
 def get_version():
     prog = shlex.split("git describe --tags --abbrev=0")
     p0 = subprocess.Popen(prog, stdout=subprocess.PIPE,
                           stderr=subprocess.PIPE)
-    stdout0, stderr0 = p0.communicate()
-    rc = p0.returncode
+    stdout0, _ = p0.communicate()
     stdout = stdout0.decode('utf-8')
     return stdout
 
@@ -47,21 +44,22 @@ def get_version():
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
-    'sphinx.ext.mathjax',
-    'sphinx_math_dollar',
-    'sphinx.ext.viewcode',
-    'sphinxcontrib.bibtex',
-    'nbsphinx',
-    'numpydoc',
-    'IPython.sphinxext.ipython_console_highlighting',
-    'sphinx.ext.githubpages',
-    'sphinx_copybutton',
-    'sphinx-prompt',
-    'sphinx_rtd_theme',
-    'breathe']
+              'sphinx.ext.mathjax',
+              'sphinx_math_dollar',
+              'sphinx.ext.viewcode',
+              'sphinxcontrib.bibtex',
+              'nbsphinx',
+              'numpydoc',
+              'IPython.sphinxext.ipython_console_highlighting',
+              'sphinx.ext.githubpages',
+              'sphinx_copybutton',
+              'sphinx-prompt',
+              'sphinx_mdinclude',
+              'sphinx_rtd_theme',
+              'breathe']
 
 breathe_projects = {
-    "microphysics":"../doxy_files/xml",
+    "microphysics": "../doxy_files/xml",
     }
 
 breathe_default_project = "microphysics"
@@ -128,7 +126,7 @@ def get_version():
 
 mathjax3_config["tex"]["macros"] = {}
 
-with open('mathsymbols.tex', 'r') as f:
+with open('mathsymbols.tex') as f:
     for line in f:
         macros = re.findall(r'\\newcommand{\\(.*?)}(\[(\d)\])?{(.+)}', line)
         for macro in macros:

Docs/source/index.rst

@@ -95,6 +95,7 @@ of state routines.
    :caption: References
    :hidden:
 
+   citing
    zreferences
 
 .. toctree::

requirements.txt

@@ -11,3 +11,4 @@ numpy>=1.13.3
 sphinx-prompt
 sphinx-math-dollar
 sphinx-copybutton
+sphinx-mdinclude