Add CITATION.cff (#171)

* Add initial CITATION.cff

* Remove distutils support from setup.py

It doesn't support some setup kwargs (e.g. package_data) and is
actually not recommended to be used directly. setuptools should
be used instead

* Remove unused argument from setup

* Enable installation of citation and license files with Euphonic

* Update CITATION.cff

- Add authors
- Update description
- Add CASTEP and Phonopy to keywords

* Update readme

* Add simple tests for LICENSE/CITATION.cff install

* Add citation mention to docs

* Update changelog

CHANGELOG.rst

@@ -24,6 +24,8 @@
 
 - Improvements:
 
+  - LICENSE and `CITATION.cff <https://citation-file-format.github.io/>`_
+    files are now included in Euphonic's installation
   - Add ability to interactively change the colormap intensity limits
     in ``euphonic-powder-map``
   - ``euphonic-optimise-dipole-parameter`` can now read from Phonopy sources

CITATION.cff

@@ -0,0 +1,33 @@
+cff-version: "1.1.0"
+message: "If you have used Euphonic in your research, please cite it as below"
+abstract: "Euphonic is a Python package for efficient simulation of phonon bandstructures, density of states and inelastic neutron scattering intensities from force constants"
+authors:
+  - family-names: "Fair"
+    given-names: "Rebecca L."
+  - family-names: "Jackson"
+    given-names: "Adam J."
+    orcid: "https://orcid.org/0000-0001-5272-6530"
+  - family-names: "King"
+    given-names: "James Charles"
+  - family-names: "Le"
+    given-names: "Manh Duc"
+  - family-names: "Pettitt"
+    given-names: "Connor"
+  - family-names: "Tucker"
+    given-names: "Gregory Scott"
+    orcid: "https://orcid.org/0000-0002-2787-8054"
+  - family-names: "Voneshen"
+    given-names: "D. J."
+title: "Euphonic"
+version: "0.5.2"
+date-released: "2021-06-02"
+license: "GPL-3.0-only"
+repository: "https://github.com/pace-neutrons/Euphonic"
+url: "euphonic.readthedocs.io/en/latest"
+keywords:
+  - "Python"
+  - "physics"
+  - "phonons"
+  - "inelastic neutron scattering"
+  - "CASTEP"
+  - "Phonopy"

MANIFEST.in

@@ -1,4 +1,7 @@
+include euphonic/LICENSE
+include euphonic/CITATION.cff
+include euphonic/data/*
+include euphonic/_version.py
+include versioneer.py
 include c/*.h
 include c/*.c
-include versioneer.py
-include euphonic/_version.py

README.rst

@@ -3,13 +3,11 @@ Euphonic
 ========
 
 Euphonic is a Python package that can efficiently calculate phonon
-bandstructures and inelastic neutron scattering intensities from a
-force constants matrix (e.g. from a .castep_bin file). While Euphonic
-is primarily a library, a command-line tool is provided for convenient
-plotting of inelastic neutron scattering intensities from
-force-constants data.
-
-Euphonic can also plot previously-calculated dispersion and density of
-states data from a CASTEP .phonon file.
+bandstructures, density of states and inelastic neutron scattering
+intensities from force constants. The force constants can be read
+from various sources, including CASTEP ``.castep_bin`` files, or Phonopy
+``phonopy.yaml`` files. While Euphonic is primarily a library, multiple
+command-line tools are also provided for convenient plotting of the above
+quantities.
 
 For more information, see the `docs <http://euphonic.readthedocs.io/en/latest/>`_.

doc/source/index.rst

@@ -11,6 +11,8 @@ precalculated phonon frequencies (e.g. CASTEP .phonon files).
 For more information on how to use Euphonic, see the
 :ref:`tutorials <tutorials>`
 
+.. contents:: :local:
+
 Installation
 ============
 
@@ -57,7 +59,7 @@ If you don't require plotting or reading of Phonopy files, just use:
   pip install .
 
 Installing the C extension
-==========================
+--------------------------
 
 By default, Euphonic will attempt to build and install the C extension,
 which can lead to increased performance and enable use of multiple cores for
@@ -99,7 +101,7 @@ before running pip install run:
   brew install llvm
 
 Installing Euphonic without the C extension
-===========================================
+-------------------------------------------
 
 If you don't need the extra performance the C extension provides, you can
 install the Python parts only with:
@@ -114,6 +116,27 @@ more difficult. The easiest way around this is running the usual install
 command first (which will install all the dependencies), then running again
 with the ``--install-option="--python-only"`` option.
 
+Citing Euphonic
+===============
+
+Euphonic has a `CITATION.cff <https://citation-file-format.github.io/>`_ that
+contains all the metadata required to cite Euphonic. The correct citation file
+for your version of Euphonic can be found in Euphonic's installation directory,
+or it can be read programatically as follows:
+
+.. code-block:: py
+
+  import yaml
+  import euphonic
+  from importlib_resources import open_text
+
+  with open_text(euphonic, 'CITATION.cff') as fp:
+      citation_data = yaml.safe_load(fp)
+
+The latest version of the citation file can also be found in Euphonic's code
+repository
+
+
 .. toctree::
    :hidden:
    :maxdepth: 2

setup.py

@@ -1,10 +1,11 @@
+import os
+import shutil
+import warnings
+
 import versioneer
-try:
-    from setuptools import setup, Extension
-    from setuptools.command.install import install
-except ImportError:
-    from distutils.core import setup, Extension
-    from distutils.command.install import install
+from setuptools import setup, Extension
+from setuptools.command.install import install
+
 
 
 class InstallCommand(install):
@@ -67,18 +68,32 @@ def get_c_extension():
     return euphonic_c_extension
 
 
-def run_setup(build_c=True):
+def run_setup():
 
-    with open('README.rst', 'r') as f:
-        long_description = f.read()
+    license_file = 'LICENSE'
+
+    # A list of files outside the Euphonic package directory that should
+    # be included in the installation in site-packages. They must
+    # also be added to MANIFEST.in
+    ex_install_files = [license_file,
+                        'CITATION.cff']
+    # MANIFEST.in will add any included files to the site-packages
+    # installation, but only if they are inside the package directory,
+    # so temporarily copy them there
+    for ex_install_file in ex_install_files:
+        try:
+            shutil.copy(ex_install_file, 'euphonic')
+        except (PermissionError, OSError) as err:
+            warnings.warn(f'{err}', stacklevel=2)
 
     packages = ['euphonic',
                 'euphonic.cli',
                 'euphonic.readers',
                 'euphonic.data']
 
-    package_data = {'euphonic' : ['data/*.json', 'data/constants_en.txt',
-                                  'data/default_en.txt']}
+    with open('README.rst', 'r') as f:
+        long_description = f.read()
+
 
     cmdclass = versioneer.get_cmdclass()
     cmdclass['install'] = InstallCommand
@@ -103,12 +118,12 @@ def run_setup(build_c=True):
             'neutron scattering intensities from modelling code output '
             '(e.g. CASTEP)'),
         license='GPLv3',
-        license_files=('LICENSE',),
+        license_files=(license_file,),
         long_description=long_description,
         long_description_content_type='text/x-rst',
         url='https://github.com/pace-neutrons/Euphonic',
         packages=packages,
-        package_data=package_data,
+        include_package_data=True,
         install_requires=[
             'numpy>=1.12.1',
             'scipy>=1.0.0',
@@ -131,4 +146,10 @@ def run_setup(build_c=True):
             'euphonic-powder-map = euphonic.cli.powder_map:main']}
     )
 
+    for ex_install_file in ex_install_files:
+        try:
+            os.remove(os.path.join('euphonic', ex_install_file))
+        except (PermissionError, OSError) as err:
+            warnings.warn(f'{err}', stacklevel=2)
+
 run_setup()

tests_and_analysis/test/euphonic_test/test_install.py

@@ -0,0 +1,17 @@
+from importlib_resources import open_text
+import yaml
+
+import euphonic
+
+
+class TestInstalledFiles:
+
+    def test_license_is_installed(self):
+        with open_text(euphonic, 'LICENSE') as fp:
+            license_data = fp.readlines()
+        assert 'GNU GENERAL PUBLIC LICENSE' in license_data[0]
+
+    def test_citation_cff_is_installed(self):
+        with open_text(euphonic, 'CITATION.cff') as fp:
+            citation_data = yaml.safe_load(fp)
+        assert 'cff-version' in citation_data