feat: add doctesting with github workflow (#2092)

Co-authored-by: antazoey <jules@apeworx.io>

.github/workflows/docs.yaml

@@ -37,6 +37,17 @@ jobs:
               name: DocumentationHTML
               path: docs/_build/ape
 
+        - name: Doctesting
+          run: |
+            sphinx-build -b doctest docs docs/_build/doctest
+            if grep -q '0 failed' docs/_build/doctest/output.txt; then
+              echo "All doctests passed!"
+            else
+              echo "Some doctests failed. See the output below."
+              cat docs/_build/doctest/output.txt
+              exit 1
+            fi
+
         - name: Commit and publish documentation changes to gh-pages branch
           run: |
               if [[ "${GITHUB_EVENT_NAME}" =~ "pull_request" ]]; then
@@ -58,3 +69,4 @@ jobs:
               branch: gh-pages
               directory: gh-pages
               github_token: ${{ secrets.GITHUB_TOKEN }}
+

docs/conf.py

@@ -9,6 +9,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import doctest
 import os
 import re
 import sys
@@ -31,6 +32,7 @@
     "sphinx_click",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
     "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
     "sphinx_plausible",
@@ -84,6 +86,20 @@
     "exclude-members": "__repr__,__weakref__,__metaclass__,__init__,model_config,model_fields,model_post_init"
 }
 
+# -- Doctest configuration -------------------------------------------------
+
+doctest_default_flags = (
+    0
+    | doctest.DONT_ACCEPT_TRUE_FOR_1
+    | doctest.ELLIPSIS
+    | doctest.IGNORE_EXCEPTION_DETAIL
+    | doctest.NORMALIZE_WHITESPACE
+)
+
+doctest_global_setup = """
+from ape import *
+"""
+
 
 def fixpath(path: str) -> str:
     """

docs/userguides/accounts.md

@@ -29,10 +29,13 @@ def test_my_contract_method(accounts):
 
 To access the same prefunded accounts in your scripts or console, use the root `accounts` object and the [test_accounts](../methoddocs/managers.html#ape.managers.accounts.AccountManager.test_accounts) property:
 
-```python
-from ape import accounts
+```{eval-rst}
+
+.. doctest::
+
+>>> from ape import accounts
 
-sender = accounts.test_accounts[0]
+>>> sender = accounts.test_accounts[0]
 ```
 
 You can configure your test accounts using your `ape-config.yaml` file:
@@ -50,10 +53,13 @@ The accounts generated from this seed are solely for testing and debugging purpo
 
 You can create a new test account by doing the following:
 
-```python
-from ape import accounts
+```{eval-rst}
+
+.. doctest::
+
+>>> from ape import accounts
 
-account = accounts.test_accounts.generate_test_account()
+>>> account = accounts.test_accounts.generate_test_account()
 ```
 
 **NOTE**: Creating a new test account means it will be unfunded by default.