DOC: Execute docs examples in CI (#3507)

Closes #2610.

Author: ievgen-kapinos

.github/workflows/github-ci.yaml

@@ -180,10 +180,17 @@ jobs:
     - name: Test with mypy
       run : |
         mypy pypdf
-    - name: Test docs build
+    - name: Install docs requirements
       run: |
         pip install -r requirements/docs.txt
-        sphinx-build --nitpicky --fail-on-warning --keep-going --show-traceback --builder html docs build/sphinx/html
+    - name: Test docs build
+      working-directory: ./docs
+      run: |
+        sphinx-build --nitpicky --fail-on-warning --keep-going --show-traceback -d _build/doctrees --builder html . _build/html
+    - name: Test docs examples
+      working-directory: ./docs
+      run: |
+        sphinx-build -d _build/doctrees --builder doctest . _build/doctest
     - name: Check with pre-commit
       run: |
         pip install -r requirements/dev.txt

docs/conf.py

@@ -14,6 +14,7 @@
 import os
 import shutil
 import sys
+from pathlib import Path
 
 sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, os.path.abspath("../"))
@@ -53,6 +54,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
     # External
     "myst_parser",
 ]
@@ -132,3 +134,93 @@
 napoleon_numpy_docstring = False  # Explicitly prefer Google style docstring
 napoleon_use_param = True  # for type hint support
 napoleon_use_rtype = False  # False, so the return type is inline with the description.
+
+# -- Options for Doctest  ------------------------------------------------------
+
+# Most of doc examples use hardcoded input and output file names.
+# To execute these examples real files need to be read and written.
+#
+# By default, documentation examples run with the working directory set to where
+# "sphinx-build" command was invoked. To avoid relative paths in docs and to
+# allow to run "sphinx-build" command from any directory, we modify the current
+# working directory in each tested file. Tests are executed against our
+# temporary directory where we have copied all nessesary resources.
+#
+# Each doc page that requires file operations must use "testsetup" directive
+# to call "pypdf_test_setup" function to prepare the test environment for that
+# page.
+#
+# def pypdf_test_setup(group: str, resources: dict[str, str] = {}) -> None
+#
+# Args:
+#   group: A unique name for group of tests. Typically we group tests by doc page.
+#       For each doc page we create a test folder under
+#       "_build/doctest/pypdf_test/<group>". This allows to avoid file name conflicts
+#       between different doc pages.
+#   resources: A dictionary of source files to copy into the test folder.
+#       Key is the destination file name (relative to the test folder).
+#       Value is the source file path (relative to the root folder).
+#
+# Examples:
+#   ```{testsetup}
+#   pypdf_test_setup("user/add-javascript", {
+#       "example.pdf": "../resources/example.pdf",
+#   })
+#   ```
+
+pypdf_test_src_root_dir = os.path.abspath(".")
+pypdf_test_dst_root_dir = os.path.abspath("_build/doctest/pypdf_test")
+if Path(pypdf_test_dst_root_dir).exists():
+   shutil.rmtree(pypdf_test_dst_root_dir)
+Path(pypdf_test_dst_root_dir).mkdir(parents=True)
+
+doctest_global_setup = f"""
+def pypdf_test_global_setup():
+    import os
+    import shutil
+    from pathlib import Path
+
+    src_root_dir = {pypdf_test_src_root_dir.__repr__()}
+    dst_root_dir = {pypdf_test_dst_root_dir.__repr__()}
+
+    global pypdf_test_orig_dir
+    pypdf_test_orig_dir = os.getcwd()
+    os.chdir(dst_root_dir)
+
+    global pypdf_test_setup
+    def pypdf_test_setup(group: str, resources: dict[str, str] = {{}}) -> None:
+        dst_dir = os.path.join(dst_root_dir, group)
+        Path(dst_dir).mkdir(parents=True)
+        os.chdir(dst_dir)
+
+        for (dst_path, src_path) in resources.items():
+            src = os.path.normpath(os.path.join(src_root_dir, src_path))
+            dst = os.path.join(dst_dir, dst_path)
+
+            shutil.copyfile(src, dst)
+
+pypdf_test_global_setup()
+"""
+
+doctest_global_cleanup = f"""
+def pypdf_test_global_cleanup():
+    import os
+
+    dst_root_dir = {pypdf_test_dst_root_dir.__repr__()}
+
+    os.chdir(pypdf_test_orig_dir)
+
+    has_files = False
+    for name in os.listdir(dst_root_dir):
+        file_name = os.path.join(dst_root_dir, name)
+        if os.path.isfile(file_name):
+            if not has_files:
+                print("Docs page was not configured propery for running code examples")
+                print("Please use 'pypdf_test_setup' function in 'testsetup' directive")
+                print("Deleting unexpected file(s) in " + dst_root_dir)
+                has_files = True
+            print(f"- {{name}}")
+            os.remove(file_name)  # Avoid side effects on other tests
+
+pypdf_test_global_cleanup()
+"""

docs/dev/documentation.md

@@ -1,5 +1,42 @@
 # Documentation
 
+This documentation is build with [Sphinx](https://www.sphinx-doc.org/) and
+hosted by [Read the Docs](https://about.readthedocs.com/)
+
+## Testing code snippets
+
+Almost all python code snippets in documentation tested using Sphinx's extension
+[sphinx.ext.doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html).
+This allows to make sure that we have no typos, missed imports and other problems in:
+- code snippets marked with `testcode` directive in `*.md` files
+- code snippets from python's docstrings imported via `autoclass` directive in `*.rst` files
+
+CI pipeline is configured run Sphinx's `doctest` build automatically for each PR.
+It is also possible to run it locally:
+
+1. First you need to install docs requirements
+
+   ```bash
+   pip install -r requirements/docs.txt
+   ```
+
+2. Change current directory
+
+   ```bash
+   cd docs
+   ```
+
+3. Run `doctest` build. It uses indirectly `sphinx-build` command line tool
+    installed with docs requrements. See
+   [Sphinx's docs](https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-build)
+   for details.
+
+   ```bash
+   make doctest
+   ```
+
+4. If everything is okay you should see in output `Doctest summary` without failures
+
 ## API Reference
 
 ### Method / Function Docstrings

docs/modules/PaperSize.rst

@@ -8,24 +8,27 @@ The PaperSize Class
 
 Add blank page with PaperSize
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: python
-    :linenos:
+
+.. testsetup ::
+
+    pypdf_test_setup("modules/PaperSize", {
+        "example.pdf": "../resources/example.pdf",
+    })
+
+.. testcode ::
 
     from pypdf import PaperSize, PdfWriter
 
-    writer = PdfWriter(clone_from="sample.pdf")
+    writer = PdfWriter(clone_from="example.pdf")
     writer.add_blank_page(PaperSize.A8.width, PaperSize.A8.height)
-    with open("output.pdf", "wb") as output_stream:
-        writer.write(output_stream)
+    writer.write("out-add-page.pdf")
 
 Insert blank page with PaperSize
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: python
-    :linenos:
+.. testcode ::
 
     from pypdf import PaperSize, PdfWriter
 
-    writer = PdfWriter(clone_from="sample.pdf")
+    writer = PdfWriter(clone_from="example.pdf")
     writer.insert_blank_page(PaperSize.A8.width, PaperSize.A8.height, 1)
-    with open("output.pdf", "wb") as output_stream:
-        writer.write(output_stream)
+    writer.write("out-insert-page.pdf")

docs/user/add-javascript.md

@@ -7,15 +7,19 @@ Adobe has documentation on its support here:
 
 ## Launch print window on opening
 
-```python
+```{testsetup}
+pypdf_test_setup("user/add-javascript", {
+    "example.pdf": "../resources/example.pdf",
+})
+```
+
+```{testcode}
 from pypdf import PdfWriter
 
 writer = PdfWriter(clone_from="example.pdf")
 
 # Add JavaScript to launch the print window on opening this PDF.
 writer.add_js("this.print({bUI:true,bSilent:false,bShrinkToFit:true});")
 
-# Write to pypdf-output.pdf.
-with open("pypdf-output.pdf", "wb") as fp:
-    writer.write(fp)
+writer.write("out-print-window.pdf")
 ```

docs/user/add-watermark.md

@@ -10,20 +10,28 @@ The process of stamping and watermarking is the same, you just need to set `over
 
 You can use {func}`~pypdf._page.PageObject.merge_page` if you don't need to transform the stamp:
 
-```python
+```{testsetup}
+pypdf_test_setup("user/add-watermark", {
+    "crazyones.pdf": "../resources/crazyones.pdf",
+    "nup-source.png": "../docs/user/nup-source.png",
+    "jpeg.pdf": "../resources/jpeg.pdf",
+})
+```
+
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 
-stamp = PdfReader("bg.pdf").pages[0]
-writer = PdfWriter(clone_from="source.pdf")
+stamp = PdfReader("jpeg.pdf").pages[0]
+writer = PdfWriter(clone_from="crazyones.pdf")
 for page in writer.pages:
     page.merge_page(stamp, over=False)  # here set to False for watermarking
 
-writer.write("out.pdf")
+writer.write("out-watermark.pdf")
 ```
 
 Otherwise use {func}`~pypdf._page.PageObject.merge_transformed_page` with {class}`~pypdf.Transformation` if you need to translate, rotate, scale, etc. the stamp before merging it to the content page.
 
-```python
+```{testcode}
 from pathlib import Path
 from typing import List, Union
 
@@ -52,7 +60,7 @@ def stamp(
     writer.write(pdf_result)
 
 
-stamp("example.pdf", "stamp.pdf", "out.pdf")
+stamp("crazyones.pdf", "jpeg.pdf", "out-scale.pdf")
 ```
 
 If you are experiencing wrongly rotated watermarks/stamps, try to use
@@ -73,7 +81,7 @@ However, you can easily convert an image to PDF image using
 [Pillow](https://pypi.org/project/Pillow/).
 
 
-```python
+```{testcode}
 from io import BytesIO
 from pathlib import Path
 from typing import List, Union
@@ -111,9 +119,8 @@ def stamp_img(
             Transformation(),
         )
 
-    with open(pdf_result, "wb") as fp:
-        writer.write(fp)
+    writer.write(pdf_result)
 
 
-stamp_img("example.pdf", "example.png", "out.pdf")
+stamp_img("crazyones.pdf", "nup-source.png", "out-image.pdf")
 ```