Merge pull request #29 from arokem/duecredit

Use due credit to point to the relevant citation

README.md

@@ -19,28 +19,29 @@ share it with others, test it, document it, and track its evolution.
 
 The project has the following structure:
 
-	shablona -
-			  |- README.md
-			  |- shablona
-					|- __init__.py
-					|- shablona.py
-					|- data
-						|- ...
-					|- tests
-						|- ...
-			  |- doc
-					|- Makefile
-					|- conf.py
-					|- sphinxext
-						|- ...
-					|- _static
-						|- ...
-			  |- setup.py
-			  |- .travis.yml
-			  |- appveyor.yml
-			  |- LICENSE
-			  |- ipynb
-		  			|- ...
+    shablona/
+      |- README.md
+      |- shablona/
+         |- __init__.py
+         |- shablona.py
+         |- due.py
+         |- data/
+            |- ...
+         |- tests/
+            |- ...
+      |- doc/
+         |- Makefile
+         |- conf.py
+         |- sphinxext/
+            |- ...
+         |- _static/
+            |- ...
+      |- setup.py
+      |- .travis.yml
+      |- appveyor.yml
+      |- LICENSE
+      |- ipynb/
+         |- ...
 
 
 In the following sections we will examine these elements one by one. First,
@@ -91,8 +92,8 @@ analysis scripts, this provides a standard file-system location for
 the data at:
 
     import os.path as op
-	  import shablona as sb
-	  data_path = op.join(sb.__path__[0], 'data')
+    import shablona as sb
+    data_path = op.join(sb.__path__[0], 'data')
 
 
 ### Testing
@@ -367,6 +368,23 @@ For more details on what you need to think about when considering
 choosing a license, see this
 [article](http://www.astrobetter.com/blog/2014/03/10/the-whys-and-hows-of-licensing-scientific-code/)!
 
+### Getting cited
+
+When others use your code in their research, they should probably cite you. To
+make their life easier, we use [duecredit](duecredit.org). This is a software
+library that allows you to annotate your code with the correct way to cite it.
+To enable `duecredit`, we have added a file `due.py` into the main directory.
+This file does not need to change at all (though you might want to occasionally
+update it from duecredit itself. It's
+[here](https://github.com/duecredit/duecredit/blob/master/duecredit/stub.py),
+under the name `stub.py`).
+
+In addition, you will want to provide a digital object identifier (DOI) to the
+article you want people to cite.
+
+To get a DOI, use the instructions in [this page](https://guides.github.com/activities/citable-code/)
+
+
 ### Scripts
 
 A scripts directory can be used as a place to experiment with your
@@ -397,7 +415,7 @@ computer under the name you will want your project to have:
 To point to your own repository on github you will have to issue
 something like the following:
 
-    git remote rm origin
+	git remote rm origin
 	git remote add origin https://github.com/arokem/smallish
 
 (replace `arokem` with your own Github user name).

shablona/__init__.py

@@ -1,2 +1,2 @@
-from .shablona import *  # noqa
 from .version import __version__  # noqa
+from .shablona import *  # noqa

shablona/due.py

@@ -0,0 +1,72 @@
+# 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
+
+See  https://github.com/duecredit/duecredit/blob/master/README.md for examples.
+
+Origin:     Originally a part of the duecredit
+Copyright:  2015-2016  DueCredit developers
+License:    BSD-2
+"""
+
+__version__ = '0.0.5'
+
+
+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
+
+    cite = load = add = _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
+    if 'due' in locals() and not hasattr(due, 'cite'):
+        raise RuntimeError(
+            "Imported due lacks .cite. DueCredit is now disabled")
+except Exception as e:
+    if type(e).__name__ != 'ImportError':
+        import logging
+        logging.getLogger("duecredit").error(
+            "Failed to import duecredit due to %s" % str(e))
+    # Initiate due stub
+    due = InactiveDueCreditCollector()
+    BibTeX = Doi = Url = _donothing_func
+
+# Emacs mode definitions
+# Local Variables:
+# mode: python
+# py-indent-offset: 4
+# tab-width: 4
+# indent-tabs-mode: nil
+# End:

shablona/shablona.py

@@ -2,10 +2,20 @@
 import pandas as pd
 import scipy.optimize as opt
 from scipy.special import erf
+from .due import due, Doi
 
 __all__ = ["Model", "Fit", "opt_err_func", "transform_data", "cumgauss"]
 
 
+# Use duecredit (duecredit.org) to provide a citation to relevant work to
+# be cited. This does nothing, unless the user has duecredit installed,
+# And calls this with duecredit (as in `python -m duecredit script.py`):
+due.cite(Doi("10.1167/13.9.30"),
+         description="Template project for small scientific Python projects",
+         tags=["reference-implementation"],
+         path='shablona')
+
+
 def transform_data(data):
     """
     Function that takes experimental data and gives us the