RFC for using sphinx doctest and continously migrating the doctest code to being tested

Author: Mathias Burger

.github/workflows/_build_test_upload.yml

@@ -504,6 +504,7 @@ jobs:
         run: |
           cd ./docs
           pip3 install -r requirements.txt
+          make doctest
           make html
           cd ..
       - name: Export Target Folder

docs/Makefile

@@ -12,7 +12,12 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+doctest:
+	$(SPHINXBUILD) -b doctest $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)"/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: help doctest Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/source/conf.py

@@ -48,7 +48,17 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.napoleon", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.intersphinx"]
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.doctest",
+]
+
+# Do not execute standard reST doctest blocks so that documentation can
+# be successively migrated to sphinx's doctest directive.
+doctest_test_doctest_blocks = ""
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

test/datapipes/__init__.py

@@ -53,9 +53,21 @@ class Shuffle(Adapter):
             - None: No-op. Introduced for backward compatibility.
 
     Example:
-        >>>  dp = IterableWrapper(range(size)).shuffle()
-        >>>  dl = DataLoader2(dp, [Shuffle(False)])
-        >>>  self.assertEqual(list(range(size)), list(dl))
+
+    .. testsetup::
+
+        from torchdata.datapipes.iter import IterableWrapper
+        from torchdata.dataloader2 import DataLoader2
+        from torchdata.dataloader2.adapter import Shuffle
+
+        size = 12
+
+    .. testcode::
+
+        dp = IterableWrapper(range(size)).shuffle()
+        dl = DataLoader2(dp, [Shuffle(False)])
+        assert list(range(size)) == list(dl)
+
     """
 
     def __init__(self, enable=True):