diff --git a/.coveragerc b/.coveragerc index 206701ecd..3e7f5b9a8 100644 --- a/.coveragerc +++ b/.coveragerc @@ -3,6 +3,7 @@ branch = True source = src/ omit = src/hdmf/_version.py + src/hdmf/_due.py src/hdmf/testing/* [report] diff --git a/.gitignore b/.gitignore index e64cc8c55..0fd29bf09 100644 --- a/.gitignore +++ b/.gitignore @@ -50,6 +50,9 @@ __pycache__/ /tests/coverage/htmlcov .coverage +# duecredit output +.duecredit.p + # tox .tox diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c3634123..9b04b5e53 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/MANIFEST.in b/MANIFEST.in index 7f69f8744..65035367b 100644 --- a/MANIFEST.in +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 62bb489a2..251cf29ae 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -35,6 +35,7 @@ doi: 10.1109/BigData47090.2019.9005648. overview_intro overview_software_architecture + overview_citing .. toctree:: :maxdepth: 2 diff --git a/docs/source/overview_citing.rst b/docs/source/overview_citing.rst index 9055458a7..331173ff6 100644 --- a/docs/source/overview_citing.rst +++ b/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 `_. + +.. _duecredit: https://github.com/duecredit/duecredit diff --git a/setup.cfg b/setup.cfg index 4363bdfa8..a0757b448 100644 --- a/setup.cfg +++ b/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 diff --git a/src/hdmf/__init__.py b/src/hdmf/__init__.py index 719d6b17d..35978710e 100644 --- a/src/hdmf/__init__.py +++ b/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 diff --git a/src/hdmf/_due.py b/src/hdmf/_due.py new file mode 100644 index 000000000..9a1c4dd08 --- /dev/null +++ b/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: