diff --git a/README.md b/README.md index 5e11f26..bd5eeee 100644 --- a/README.md +++ b/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). diff --git a/shablona/__init__.py b/shablona/__init__.py index c182017..095b8c7 100644 --- a/shablona/__init__.py +++ b/shablona/__init__.py @@ -1,2 +1,2 @@ -from .shablona import * # noqa from .version import __version__ # noqa +from .shablona import * # noqa diff --git a/shablona/due.py b/shablona/due.py new file mode 100644 index 0000000..35d35d7 --- /dev/null +++ b/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: diff --git a/shablona/shablona.py b/shablona/shablona.py index 7a22286..50976dc 100644 --- a/shablona/shablona.py +++ b/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