generate authors list from AUTHORS file

- reformatted AUTHORS
- create MDAnalysisData/authors.py on installation (with a fall back)
  and make MDAnalysisData.__authors__ available;
  uses setup.dynamic_author_list() that was written by @jbarnoud with
  modifications by @tylerjereddy and @lilyminium and originally included
  in MDAnalysis setup.py under GPL v2+. All authors agreed to re-license
  their code under the BSD 3-clause license so that dynamic_author_list()
  could be included here.
  See #49 (comment)
  for the agreement to re-license.
- add tests for __authors__ and __version__
- use __authors__ in doc generation (together with latest year via datetime)
- update CHANGELOG

Co-authored-by: Irfan Alibay <IAlibay@users.noreply.github.com>

Author: orbeckst

.gitignore

@@ -0,0 +1 @@
+MDAnalysisData/authors.py

AUTHORS

@@ -3,13 +3,19 @@ Authors of MDAnalysisData
 
 Contributors to MDAnalysisData are listed under the year of their
 first contribution. Full names, GitHub handles (@name) or email
-addresses are all optional.
+addresses (all in parentheses) are all optional.
+
+Chronological list of authors
+-----------------------------
 
 2018
-   - Oliver Beckstein @orbeckst
-   - Shujie Fan @VOD555
-   - Micaela Matta @micaela-matta
-   - Richard J. Gowers @richardjgowers
+
+  - Oliver Beckstein (@orbeckst)
+  - Shujie Fan (@VOD555)
+  - Micaela Matta (@micaela-matta)
+  - Richard J. Gowers (@richardjgowers)
 
 2020
-   - Lily Wang @lilyminium
+
+  - Lily Wang (@lilyminium)
+  

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - docs for how to contribute a new dataset (#46)
+- new `MDAnalysis.__authors__` attribute with the list of AUTHORS
 
 ### Changes
 - update online docs theme (#43)

MDAnalysisData/__init__.py

@@ -9,10 +9,15 @@
 
 from . import datasets
 
-
-
-
-
 from ._version import get_versions
 __version__ = get_versions()['version']
 del get_versions
+
+try:
+    from .authors import __authors__
+except ImportError:
+    import warnings
+    warnings.warn('Could not find authors.py, __authors__ will be the '
+                  'generic MDAnalysis team.')
+    __authors__ = ["The MDAnalysis Development Team"]
+    del warnings

MDAnalysisData/tests/test_package_metadata.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+import sys
+from six.moves import reload_module
+import pytest
+
+import MDAnalysisData
+
+
+def test_authors():
+    authors = MDAnalysisData.__authors__
+    assert authors[:5] == ["Oliver Beckstein", "Shujie Fan",
+                           "Richard J. Gowers", "Micaela Matta",
+                           "Lily Wang"]
+
+
+def test_default_authors(monkeypatch):
+    # authors.py did not exist and could not be imported
+    monkeypatch.setitem(sys.modules, 'MDAnalysisData.authors', None)
+    with pytest.warns(UserWarning,
+                      match="Could not find authors.py, __authors__ will "
+                            "be the generic MDAnalysis team."):
+        reload_module(MDAnalysisData)
+    authors = MDAnalysisData.__authors__
+    assert authors == ["The MDAnalysis Development Team"]
+
+
+def test_version():
+    # very generic because versioneer will provide different strings depending
+    # on the repository status
+    assert isinstance(MDAnalysisData.__version__, str)

docs/conf.py

@@ -12,16 +12,19 @@
 # serve to show the default.
 
 import sys, os
+import datetime
+
+import sphinx_rtd_theme
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
+#
 # make sure sphinx always uses the current branch
 sys.path.insert(0, os.path.abspath('..'))
 
-import sphinx_rtd_theme
+# to get authors and version
+import MDAnalysisData
 
 # -- General configuration -----------------------------------------------------
 
@@ -63,18 +66,19 @@
 master_doc = 'index'
 
 # General information about the project.
+author_list = MDAnalysisData.__authors__
+authors = u', '.join(author_list[:-1]) + u', and ' + author_list[-1]
 project = u'MDAnalysisData'
-author = (u'Oliver Beckstein, Shujie Fan, Micaela Matta, '
-          u'Richard J. Gowers, Lily Wang')
-copyright = u'2018-2020, ' + author
+now = datetime.datetime.now()
+copyright = u'2018-{}, '.format(now.year) + authors
 
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = __import__('MDAnalysisData').__version__
+release = MDAnalysisData.__version__
 # The short X.Y version.
 version = ".".join(release.split('.')[:2])
 
@@ -240,7 +244,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'MDAnalysisData.tex', u'MDAnalysisData Documentation',
-     author, 'manual'),
+     authors, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -270,7 +274,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     (master_doc, 'MDAnalysisData', u'MDAnalysisData Documentation',
-     author.split(), 1)
+     authors.split(), 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -284,7 +288,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'MDAnalysisData', u'MDAnalysisData Documentation',
-     author, 'MDAnalysisData', 'Datasets for MDAnalysis',
+     authors, 'MDAnalysisData', 'Datasets for MDAnalysis',
      'Miscellaneous'),
 ]
 
@@ -301,5 +305,5 @@
 # Configuration for intersphinx: refer to the Python standard library
 # and other packages used by MDAnalysis
 intersphinx_mapping = {'https://docs.python.org/': None,
-                       'https://www.mdanalysis.org/docs/': None,
+                       'https://docs.mdanalysis.org/stable': None,
                        }

setup.py

@@ -19,12 +19,94 @@
 from setuptools import setup, find_packages
 import versioneer
 
+import os
+import warnings
 import codecs
 
+
+def abspath(file):
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                        file)
+
+
+def dynamic_author_list():
+    """Generate __authors__ from AUTHORS
+
+    This function generates authors.py that contains the list of the
+    authors from the AUTHORS file. This avoids having that list maintained in
+    several places. Note that AUTHORS is sorted chronologically while we want
+    __authors__ in authors.py to be sorted alphabetically.
+
+    The authors are written in AUTHORS as bullet points under the
+    "Chronological list of authors" title.
+    """
+
+    # The dynamic_author_list() function was taken from MDAnalysis's setup.py
+    # file, which is licensed under GPL v2+. All original authors of the
+    # function (@jbarnoud, @tylerjereddy, @lilyminium) agreed to re-license the
+    # code under the BSD 3-clause license
+    # (https://github.com/MDAnalysis/MDAnalysisData/pull/49#discussion_r672489685)
+    # so that it can be included here with modifictions necessary for
+    # MDAnalysisData.
+
+    authors = []
+    with codecs.open(abspath('AUTHORS'), encoding='utf-8') as infile:
+        # An author is a bullet point under the title "Chronological list of
+        # authors". We first want move the cursor down to the title of
+        # interest.
+        for line_no, line in enumerate(infile, start=1):
+            if line.rstrip() == "Chronological list of authors":
+                break
+        else:
+            # If we did not break, it means we did not find the authors.
+            raise IOError('EOF before the list of authors')
+        # Skip the next line as it is the title underlining
+        line = next(infile)
+        line_no += 1
+        if line[:4] != '----':
+            raise IOError('Unexpected content on line {0}, '
+                          'should be a string of "-".'.format(line_no))
+        # Add each bullet point as an author
+        for line in infile:
+            if line.strip()[:2] == '- ':
+                # This is a bullet point, so it should be an author name.
+                name = line.strip()[2:].strip()
+                # Remove any @-handles in "A.U. Thor (@donnergott)"
+                name = name.split("(")[0].strip()
+                authors.append(name)
+
+    # So far, the list of authors is sorted chronologically. We want it
+    # sorted alphabetically of the last name.
+    authors.sort(key=lambda name: name.split()[-1])
+
+    # Write the authors.py file.
+    out_path = abspath('MDAnalysisData/authors.py')
+    with codecs.open(out_path, 'w', encoding='utf-8') as outfile:
+        # Write the header
+        header = '''\
+#-*- coding:utf-8 -*-
+
+# This file is generated from the AUTHORS file during the installation process.
+# Do not edit it as your changes will be overwritten.
+'''
+        print(header, file=outfile)
+
+        # Write the list of authors as a python list
+        template = u'__authors__ = [\n{}\n]'
+        author_string = u',\n'.join(u'    u"{}"'.format(name)
+                                    for name in authors)
+        print(template.format(author_string), file=outfile)
+
+
 if __name__ == '__main__':
     with codecs.open("README.md", encoding="utf-8") as summary:
         LONG_DESCRIPTION = summary.read()
 
+    try:
+        dynamic_author_list()
+    except (OSError, IOError):
+        warnings.warn('Cannot write the list of authors.')
+
     CLASSIFIERS = [
         'Development Status :: 4 - Beta',
         'Environment :: Console',
@@ -74,6 +156,6 @@
                             'setuptools',
                             'tqdm',
           ],
-          tests_require=['pytest-mock', 'pytest'],
+          tests_require=['pytest', 'pytest-mock'],
           zip_safe=True,
     )