Turn on basic doctests for modules and .rst docs (#511)

* Turn on basic doctests for modules and .rst docs
* Short documentation of docstrings with link to syntax
* Added docstring tests to example module

Author: mtauraso

docs/practices/unit_testing.rst

@@ -29,7 +29,18 @@ expected.
 
 It's also worth noting that if you want to write exploratory tests as you develop
 your code, but you *do not* want those tests to be included in automated test runs,
-feel free to place those tests in a directory outside of the ``./tests`` directory.
+feel free to place those tests in a directory outside of the ``./tests`` and 
+``./src`` directories.
 
 Note that ``pytest`` will recursively search subdirectories inside of ``./tests``
 while searching for tests to run.
+
+doctests
+-------------------------------------------------------------------------------
+
+In addition to the usual ways of writing unit tests with pytest, our template
+supports tests embedded in documentation using pytest's 
+`doctest <https://doc.pytest.org/en/latest/how-to/doctest.html>`_ component. 
+Documentation comments in all source files, as well as ``.rst`` files in the ``./docs`` 
+directory can contain doctests in the format outlined 
+`here <https://doc.pytest.org/en/latest/how-to/doctest.html>`_.

python-project-template/pyproject.toml.jinja

@@ -63,7 +63,10 @@ write_to = "src/{{package_name}}/_version.py"
 [tool.pytest.ini_options]
 testpaths = [
     "tests",
+    "src",
+    "docs",
 ]
+addopts = "--doctest-modules --doctest-glob=*.rst"
 
 [tool.black]
 line-length = 110

python-project-template/src/{{package_name}}/{% if create_example_module %}example_module.py{% endif %}

@@ -4,6 +4,12 @@
 def greetings() -> str:
     """A friendly greeting for a future friend.
 
+    Example:
+    >>> greetings()
+    'Hello from LINCC-Frameworks!'
+
+    Note: this example becomes a unit test via doctests
+
     Returns
     -------
     str
@@ -15,6 +21,12 @@ def greetings() -> str:
 def meaning() -> int:
     """The meaning of life, the universe, and everything.
 
+    Example:
+    >>> meaning()
+    42
+
+    Note: this example becomes a unit test via doctests
+
     Returns
     -------
     int