Enable duecredit and add referece for magdir (#293)

Include the backend code for duecredit (http://duecredit.org)
This will enable us to add references using it incrementally.
Also, fill in the reference for the DipoleMagDir class.

doc/changelog.rst

@@ -40,6 +40,12 @@ Version 0.5
 * Better navigation for long pages in the docs by adding a sidebar with links
   to subsections.
   (`PR 275 <https://github.com/fatiando/fatiando/pull/275>`__)
+* Added back-end support for decorators from `duecredit
+  <https://github.com/duecredit/duecredit/>`__ to be added to methods. This
+  allows a report for per-method citations based on the methods used in a given
+  script. Currently only implemented for `gravmag/magdir` but will be added to
+  all methods in time.
+  (`PR 293 <https://github.com/fatiando/fatiando/pull/293>`__)
 
 
 

fatiando/_our_duecredit.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:

fatiando/gravmag/magdir.py

@@ -24,12 +24,15 @@
 from ..utils import ang2vec, vec2ang, safe_dot
 from . import sphere
 from ..constants import G, CM, T2NT, SI2EOTVOS
+from .._our_duecredit import due, Doi, BibTeX
 
 
+@due.dcite(Doi("10.5194/npg-22-215-2015"),
+           description='Estimates total mag. dir. of approx. spherical bodies')
 class DipoleMagDir(Misfit):
     """
     Estimate the magnetization vector of a set of dipoles from magnetic
-    total field anomaly.
+    total field anomaly using the method of Oliveira Jr. et al. (2015).
 
     By using the well-known first-order approximation of the total field
     anomaly (Blakely, 1996, p. 179) produced by a set of dipoles, the
@@ -67,6 +70,11 @@ class DipoleMagDir(Misfit):
     Blakely, R. (1996), Potential theory in gravity and magnetic applications:
     CUP
 
+    Oliveira Jr., V. C., D. P. Sales, V. C. F. Barbosa, and L. Uieda (2015),
+    Estimation of the total magnetization direction of approximately spherical
+    bodies, Nonlin. Processes Geophys., 22(2), 215-232,
+    doi:10.5194/npg-22-215-2015.
+
     Examples:
 
     Estimation of the total magnetization vector of dipoles with known centers