[patch] Run Doctest (#18)

* Add doctest

* Fix import alarm example

* Modify deprecator example to ignore the stated output

I can't get the test to nicely see the error message; since we anyhow have unit tests for this I am not hung up on whether the docstrings remain perfectly verbatim correct and am content to leave the printed warning as plain-text docstring instead of tested-code docstring.

* Skip deprecate doctests since checking warnings is awkward

* Revert to nicer output formatting

Now that doctest ignores it anyway

---------

Co-authored-by: Marvin Poul <[email protected]>

pyiron_snippets/deprecate.py

@@ -24,33 +24,33 @@ class Deprecator:
     If message and version are not initialized or given during the decorating
     call the respective parts are left out from the message.
 
+    >>> from pyiron_snippets.deprecate import Deprecator
+    >>>
     >>> deprecate = Deprecator()
     >>> @deprecate
     ... def foo(a, b):
     ...     pass
-    >>> foo(1, 2)
+    >>> foo(1, 2) # doctest: +SKIP
     DeprecationWarning: __main__.foo is deprecated
 
     >>> @deprecate("use bar() instead")
     ... def foo(a, b):
     ...     pass
-    >>> foo(1, 2)
+    >>> foo(1, 2) # doctest: +SKIP
     DeprecationWarning: __main__.foo is deprecated: use bar instead
 
     >>> @deprecate("use bar() instead", version="0.4.0")
     ... def foo(a, b):
     ...     pass
-    >>> foo(1, 2)
-    DeprecationWarning: __main__.foo is deprecated: use bar instead.  It is not
-    guaranteed to be in service in vers. 0.4.0
+    >>> foo(1, 2) # doctest: +SKIP
+    DeprecationWarning: __main__.foo is deprecated: use bar instead.  It is not guaranteed to be in service in vers. 0.4.0
 
     >>> deprecate = Deprecator(message="I say no!", version="0.5.0")
     >>> @deprecate
     ... def foo(a, b):
     ...     pass
-    >>> foo(1, 2)
-    DeprecationWarning: __main__.foo is deprecated: I say no!  It is not
-    guaranteed to be in service in vers. 0.5.0
+    >>> foo(1, 2) # doctest: +SKIP
+    DeprecationWarning: __main__.foo is deprecated: I say no!  It is not guaranteed to be in service in vers. 0.5.0`
 
     Alternatively the decorator can also be called with `arguments` set to a dictionary
     mapping names of keyword arguments to deprecation messages.  In this case the
@@ -62,7 +62,7 @@ class Deprecator:
     ... def foo(bar=None, baz=None):
     ...     pass
     >>> foo(baz=True)
-    >>> foo(bar=True)
+    >>> foo(bar=True) # doctest: +SKIP
     DeprecationWarning: __main__.foo(bar=True) is deprecated: use baz instead.
 
     As a short-cut, it is also possible to pass the values in the arguments dict
@@ -72,8 +72,9 @@ class Deprecator:
     ... def foo(bar=None, baz=None):
     ...     pass
     >>> foo(baz=True)
-    >>> foo(bar=True)
+    >>> foo(bar=True) # doctest: +SKIP
     DeprecationWarning: __main__.foo(bar=True)  is deprecated: use baz instead.
+
     """
 
     def __init__(self, message=None, version=None, pending=False):

pyiron_snippets/import_alarm.py

@@ -20,15 +20,15 @@ class ImportAlarm:
     >>> try:
     ...     from mystery_package import Enigma, Puzzle, Conundrum
     ...     import_alarm = ImportAlarm()
-    >>> except ImportError:
-    >>>     import_alarm = ImportAlarm(
+    ... except ImportError:
+    ...     import_alarm = ImportAlarm(
     ...         "MysteryJob relies on mystery_package, but this was unavailable. Please ensure your python environment "
     ...         "has access to mystery_package, e.g. with `conda install -c conda-forge mystery_package`"
     ...     )
     ...
     >>> class MysteryJob:
     ...     @import_alarm
-    ...     def __init__(self, project, job_name)
+    ...     def __init__(self, project, job_name):
     ...         super().__init__()
     ...         self.riddles = [Enigma(), Puzzle(), Conundrum()]
 

tests/unit/test_docs.py

@@ -0,0 +1,26 @@
+import doctest
+import pkgutil
+import unittest
+
+import pyiron_snippets
+
+
+def load_tests(loader, tests, ignore):
+    for importer, name, ispkg in pkgutil.walk_packages(
+        pyiron_snippets.__path__, pyiron_snippets.__name__ + '.'
+    ):
+        tests.addTests(doctest.DocTestSuite(name))
+    return tests
+
+
+class TestTriggerFromIDE(unittest.TestCase):
+    """
+    Just so we can instruct it to run unit tests here with a gui run command on the file
+    """
+
+    def test_void(self):
+        pass
+
+
+if __name__ == '__main__':
+    unittest.main()