test(docs): improve the doctest configuration

Signed-off-by: behnazh-w <behnaz.hassanshahi@oracle.com>

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2024, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # See https://pre-commit.com for more information
@@ -166,7 +166,9 @@ repos:
   hooks:
   - id: pytest
     name: Run unit tests
-    entry: python -W always::DeprecationWarning -m pytest -c pyproject.toml --cov-config pyproject.toml
+    entry: |
+      python -W always::DeprecationWarning -m pytest -c pyproject.toml --cov-config pyproject.toml
+      src/macaron/ tests/ docs/
     language: system
     verbose: true
     always_run: true

CONTRIBUTING.md

@@ -165,7 +165,24 @@ This repository is set up to test either standalone or as a pre-push git hook. T
 ```bash
 make test
 ```
-which runs all unit tests in both your local environment. Test code and branch coverage is already tracked using [coverage](https://github.com/nedbat/coveragepy) and the [pytest-cov](https://github.com/pytest-dev/pytest-cov) plugin for pytest, and it measures how much code in the `src/package/` folder is covered by tests.
+which runs all unit tests in your local environment. You can also add tests to the docstrings in the Python source files or documentation `.rst` files, which will be picked up by pytest from `src/` and `docs/` directories. Here is an example:
+
+```python
+def do_something(value: bool = False) -> bool:
+    """Return true, always.
+
+    Test this function by adding the following code to the docstring:
+    .. code: pycon
+
+        >>> s = Something()
+        >>> s.do_something(False)
+        True
+        >>> s.do_something(value=True)
+        True
+    """
+```
+
+Test code and branch coverage is already tracked using [coverage](https://github.com/nedbat/coveragepy) and the [pytest-cov](https://github.com/pytest-dev/pytest-cov) plugin for pytest, and it measures how much code in the `src/macaron/` folder is covered by tests.
 
 You can also run integration tests locally:
 ```bash

pyproject.toml

@@ -232,12 +232,13 @@ max-line-length = 120
 # https://docs.pytest.org/en/latest/reference/reference.html#command-line-flags
 [tool.pytest.ini_options]
 minversion = "7.0"
-addopts = "--verbose --doctest-modules -ra --cov macaron"  # Consider adding --pdb
+addopts = """-vv -ra --tb native \
+    --doctest-modules --doctest-continue-on-failure --doctest-glob '*.rst' \
+    --cov macaron \
+"""  # Consider adding --pdb
+# https://docs.python.org/3/library/doctest.html#option-flags
 doctest_optionflags = "IGNORE_EXCEPTION_DETAIL"
-testpaths = [
-    "src/macaron",  # this is included to run doctest on examples
-    "tests",
-]
+
 env = [
     "PYTHONWARNINGS=always::DeprecationWarning",
 ]

src/macaron/config/defaults.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2024, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 """This module provides functions to manage default values."""
@@ -76,7 +76,7 @@ def get_list(
         .. code-block:: python3
 
             allowed_hosts = config_parser.get_list("git", "allowed_hosts")
-            # allowed_hosts == ['github.com', 'boo.com gitlab.com', 'host com']
+            allowed_hosts == ["github.com", "boo.com gitlab.com", "host com"]
         """
         try:
             value = self.get(section, item)