DOC: Execute docs examples in CI

.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

@@ -12,6 +12,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 import datetime
 import os
+import pathlib
 import shutil
 import sys
 
@@ -53,6 +54,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
     # External
     "myst_parser",
 ]
@@ -132,3 +134,30 @@
 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.
+
+pypdf_test_dir = os.path.abspath("_build/doctest/pypdf_test")
+if pathlib.Path(pypdf_test_dir).exists():
+    shutil.rmtree(pypdf_test_dir)
+shutil.copytree("../resources", pypdf_test_dir)
+shutil.copy("user/nup-source.png", pypdf_test_dir)
+
+doctest_global_setup = f"""
+import os as pypdf_test_os
+pypdf_orig_dir = pypdf_test_os.getcwd()
+pypdf_test_os.chdir({pypdf_test_dir.__repr__()})
+"""
+
+doctest_global_cleanup = """
+pypdf_test_os.chdir(pypdf_orig_dir)
+"""

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

@@ -15,8 +15,7 @@ Add blank page with PaperSize
 
     writer = PdfWriter(clone_from="sample.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("paper-size-add-page.pdf")
 
 Insert blank page with PaperSize
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -27,5 +26,4 @@ Insert blank page with PaperSize
 
     writer = PdfWriter(clone_from="sample.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("paper-size-insert-size.pdf")

docs/user/add-javascript.md

@@ -7,15 +7,13 @@ Adobe has documentation on its support here:
 
 ## Launch print window on opening
 
-```python
+```{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("add-javascript.pdf")
 ```

docs/user/add-watermark.md

@@ -10,20 +10,20 @@ 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
+```{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("add-watermark-underlay.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 +52,7 @@ def stamp(
     writer.write(pdf_result)
 
 
-stamp("example.pdf", "stamp.pdf", "out.pdf")
+stamp("crazyones.pdf", "jpeg.pdf", "add-watermark-transform.pdf")
 ```
 
 If you are experiencing wrongly rotated watermarks/stamps, try to use
@@ -73,7 +73,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 +111,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", "add-watermark-direct.pdf")
 ```