Add duecredit citation (#488)

.coveragerc

@@ -3,6 +3,7 @@ branch = True
 source = src/
 omit =
     src/hdmf/_version.py
+    src/hdmf/_due.py
     src/hdmf/testing/*
 
 [report]

.gitignore

@@ -50,6 +50,9 @@ __pycache__/
 /tests/coverage/htmlcov
 .coverage
 
+# duecredit output
+.duecredit.p
+
 # tox
 .tox
 

CHANGELOG.md

@@ -42,7 +42,7 @@
 - Fix bug in slicing tables with DynamicTableRegions. @ajtritt (#449)
 - Add testing for Python 3.9 and using pre-release packages. @ajtritt, @rly (#459, #472)
 - Improve contributing guide. @rly (#474)
-- Add citation information to documentation. @rly (#477)
+- Add citation information to documentation and support for duecredit tool. @rly (#477, #488)
 
 ### Bug fixes
 - Fix development package dependency issues. @rly (#431)

MANIFEST.in

@@ -1,4 +1,4 @@
-include license.txt Legal.txt versioneer.py src/hdmf/_version.py
+include license.txt Legal.txt versioneer.py src/hdmf/_version.py src/hdmf/_due.py
 include requirements.txt requirements-dev.txt requirements-doc.txt requirements-min.txt
 include test.py tox.ini
 graft tests

docs/source/index.rst

@@ -35,6 +35,7 @@ doi: 10.1109/BigData47090.2019.9005648.
 
    overview_intro
    overview_software_architecture
+   overview_citing
 
 .. toctree::
    :maxdepth: 2

docs/source/overview_citing.rst

@@ -3,6 +3,9 @@
 Citing HDMF
 ============
 
+BibTeX entry
+------------
+
 If you use HDMF in your research, please use the following citation:
 
 .. code-block:: bibtex
@@ -16,3 +19,33 @@ If you use HDMF in your research, please use the following citation:
     number={},
     pages={165-179},
     doi={10.1109/BigData47090.2019.9005648}}
+
+Using duecredit
+-----------------
+
+Citations can be generated using duecredit_. To install duecredit, run ``pip install duecredit``.
+
+You can obtain a list of citations for your Python script, e.g., ``yourscript.py``, using:
+
+.. code-block:: bash
+
+   cd /path/to/your/module
+   python -m duecredit yourscript.py
+
+Alternatively, you can set the environment variable ``DUECREDIT_ENABLE=yes``
+
+.. code-block:: bash
+
+   DUECREDIT-ENABLE=yes python yourscript.py
+
+Citations will be saved in a hidden file (``.duecredit.p``) in the current directory. You can then use the duecredit_
+command line tool to export the citations to different formats. For example, you can display your citations in
+BibTeX format using:
+
+.. code-block:: bash
+
+   duecredit summary --format=bibtex
+
+For more information on using duecredit, please consult its `homepage <https://github.com/duecredit/duecredit>`_.
+
+.. _duecredit: https://github.com/duecredit/duecredit

setup.cfg

@@ -21,6 +21,7 @@ exclude =
   docs/source/conf.py
   versioneer.py
   src/hdmf/_version.py
+  src/hdmf/_due.py
 per-file-ignores =
   docs/gallery/*:E402,T001
   docs/source/tutorials/*:E402

src/hdmf/__init__.py

@@ -6,3 +6,19 @@
 from ._version import get_versions  # noqa: E402
 __version__ = get_versions()['version']
 del get_versions
+
+
+from ._due import due, BibTeX  # noqa: E402
+due.cite(BibTeX("""
+@INPROCEEDINGS{9005648,
+  author={A. J. {Tritt} and O. {Rübel} and B. {Dichter} and R. {Ly} and D. {Kang} and E. F. {Chang} and L. M. {Frank} and K. {Bouchard}},
+  booktitle={2019 IEEE International Conference on Big Data (Big Data)},
+  title={HDMF: Hierarchical Data Modeling Framework for Modern Science Data Standards},
+  year={2019},
+  volume={},
+  number={},
+  pages={165-179},
+  doi={10.1109/BigData47090.2019.9005648}}
+"""), description="HDMF: Hierarchical Data Modeling Framework for Modern Science Data Standards",  # noqa: E501
+         path="hdmf/", version=__version__, cite_module=True)
+del due, BibTeX

src/hdmf/_due.py

@@ -0,0 +1,74 @@
+# emacs: at the end of the file
+# ex: set sts=4 ts=4 sw=4 et:
+# ## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### #
+"""
+
+Stub file for a guaranteed safe import of duecredit constructs:  if duecredit
+is not available.
+
+To use it, place it into your project codebase to be imported, e.g. copy as
+
+    cp stub.py /path/tomodule/module/due.py
+
+Note that it might be better to avoid naming it duecredit.py to avoid shadowing
+installed duecredit.
+
+Then use in your code as
+
+    from .due import due, Doi, BibTeX, Text
+
+See  https://github.com/duecredit/duecredit/blob/master/README.md for examples.
+
+Origin:     Originally a part of the duecredit
+Copyright:  2015-2019  DueCredit developers
+License:    BSD-2
+"""
+
+__version__ = '0.0.8'
+
+
+class InactiveDueCreditCollector(object):
+    """Just a stub at the Collector which would not do anything"""
+    def _donothing(self, *args, **kwargs):
+        """Perform no good and no bad"""
+        pass
+
+    def dcite(self, *args, **kwargs):
+        """If I could cite I would"""
+        def nondecorating_decorator(func):
+            return func
+        return nondecorating_decorator
+
+    active = False
+    activate = add = cite = dump = load = _donothing
+
+    def __repr__(self):
+        return self.__class__.__name__ + '()'
+
+
+def _donothing_func(*args, **kwargs):
+    """Perform no good and no bad"""
+    pass
+
+
+try:
+    from duecredit import due, BibTeX, Doi, Url, Text
+    if 'due' in locals() and not hasattr(due, 'cite'):
+        raise RuntimeError(
+            "Imported due lacks .cite. DueCredit is now disabled")
+except Exception as e:
+    if not isinstance(e, ImportError):
+        import logging
+        logging.getLogger("duecredit").error(
+            "Failed to import duecredit due to %s" % str(e))
+    # Initiate due stub
+    due = InactiveDueCreditCollector()
+    BibTeX = Doi = Url = Text = _donothing_func
+
+# Emacs mode definitions
+# Local Variables:
+# mode: python
+# py-indent-offset: 4
+# tab-width: 4
+# indent-tabs-mode: nil
+# End: