DOC: Execute docs examples in CI

.github/workflows/github-ci.yaml

@@ -184,6 +184,9 @@ jobs:
       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 examples
+      run: |
+        sphinx-build --nitpicky --fail-on-warning --keep-going --show-traceback --builder doctest docs build/sphinx/html
     - name: Check with pre-commit
       run: |
         pip install -r requirements/dev.txt

docs/conf.py

@@ -53,6 +53,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.doctest",
     # External
     "myst_parser",
 ]

docs/user/add-javascript.md

@@ -7,7 +7,7 @@ Adobe has documentation on its support here:
 
 ## Launch print window on opening
 
-```python
+```{testcode}
 from pypdf import PdfWriter
 
 writer = PdfWriter(clone_from="example.pdf")

docs/user/add-watermark.md

@@ -10,7 +10,7 @@ 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]
@@ -23,7 +23,7 @@ writer.write("out.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
 
@@ -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

docs/user/adding-pdf-annotations.md

@@ -12,7 +12,7 @@ To circumvent this, make sure to add the `/C` entry to the annotation, being an
 
 ## Attachments
 
-```python
+```{testcode}
 from pypdf import PdfWriter
 
 writer = PdfWriter()
@@ -34,7 +34,7 @@ If you want to add text in a box like this
 
 you can use {class}`~pypdf.annotations.FreeText`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import FreeText
 
@@ -83,7 +83,7 @@ If you want to add a line like this:
 
 you can use {class}`~pypdf.annotations.Line`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import Line
 
@@ -115,7 +115,7 @@ If you want to add a line like this:
 
 you can use {class}`~pypdf.annotations.PolyLine`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import PolyLine
 from pypdf.generic import ArrayObject, FloatObject, NameObject
@@ -149,7 +149,7 @@ If you want to add a rectangle like this:
 
 you can use {class}`~pypdf.annotations.Rectangle`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import Rectangle
 
@@ -183,7 +183,7 @@ If you want to add a circle like this:
 
 you can use {class}`~pypdf.annotations.Ellipse`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import Ellipse
 
@@ -212,7 +212,7 @@ If you want to add a polygon like this:
 
 you can use {class}`~pypdf.annotations.Polygon`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import Polygon
 
@@ -241,7 +241,7 @@ Manage the Popup windows for markups, looks like this:
 
 you can use {py:class}`~pypdf.annotations.Popup`:
 
-```python
+```{testcode}
 from pypdf.annotations import Popup, Text
 
 # Arrange
@@ -274,7 +274,7 @@ the parent annotation with which this popup annotation shall be associated.
 
 If you want to add a link, you can use {class}`~pypdf.annotations.Link`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import Link
 
@@ -298,7 +298,7 @@ with open("annotated-pdf.pdf", "wb") as fp:
 
 You can also add internal links:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import Link
 from pypdf.generic import Fit
@@ -337,7 +337,7 @@ If you want to highlight text like this:
 
 you can use {class}`~pypdf.annotations.Highlight`:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 from pypdf.annotations import Highlight
 from pypdf.generic import ArrayObject, FloatObject

docs/user/cropping-and-transforming.md

@@ -6,7 +6,7 @@ Cropping works by adjusting the viewbox. That means content that was cropped
 away can still be restored.
 ```
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 
 reader = PdfReader("example.pdf")
@@ -37,7 +37,7 @@ The most typical rotation is a clockwise rotation of the page by multiples of
 90 degrees. That is done when the orientation of the page is wrong. You can
 do that with the {func}`~pypdf._page.PageObject.rotate` method:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 
 reader = PdfReader("input.pdf")
@@ -63,7 +63,7 @@ contents and does not change the mediabox or cropbox.
 
 is the result of
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter, Transformation
 
 # Get the data
@@ -86,7 +86,7 @@ with open("merged-foo.pdf", "wb") as fp:
 
 ![](merge-45-deg-rot.png)
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter, Transformation
 
 # Get the data
@@ -110,7 +110,7 @@ with open("merged-foo.pdf", "wb") as fp:
 
 If you add the `expand` parameter:
 
-```python
+```{testcode}
 transformation = Transformation().rotate(45)
 page_box.add_transformation(transformation)
 page_base.merge_page(page_box, expand=True)
@@ -122,7 +122,7 @@ you get:
 
 Alternatively, you can move the merged image a bit to the right by using
 
-```python
+```{testcode}
 op = Transformation().rotate(45).translate(tx=50)
 ```
 
@@ -139,7 +139,7 @@ Typically, you want to combine both.
 
 ### Scaling both the Page and contents together
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 
 # Read the input
@@ -160,7 +160,7 @@ writer.write("out.pdf")
 The content is scaled around the origin of the coordinate system.
 Typically, that is the lower-left corner.
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter, Transformation
 
 # Read the input
@@ -181,7 +181,7 @@ writer.write("out-pg-transform.pdf")
 
 To scale the page by `sx` in the X direction and `sy` in the Y direction:
 
-```python
+```{testcode}
 from pypdf.generic import RectangleObject
 
 mb = page.mediabox
@@ -191,7 +191,7 @@ page.mediabox = self.mediabox.scale(sx, sy)
 
 If you wish to have more control, you can adjust the various page boxes directly:
 
-```python
+```{testcode}
 from pypdf.generic import RectangleObject
 
 mb = page.mediabox
@@ -211,7 +211,7 @@ page.artbox = RectangleObject((mb.left, mb.bottom, mb.right, mb.top))
 In case anybody has good reasons to use/expect `trimbox`, you can add the
 following code to get the old behavior:
 
-```python
+```{testcode}
 pypdf._page.MERGE_CROP_BOX = "trimbox"
 ```
 
@@ -223,7 +223,7 @@ We have designed the following business card (A8 format) to advertise our new st
 
 We would like to copy this card sixteen times on an A4 page, to print it, cut it, and give it to all our friends. Having learned about the {func}`~pypdf._page.PageObject.merge_page` method and the {class}`~pypdf.Transformation` class, we run the following code. Notice that we had to tweak the media box of the source page to extend it, which is already a dirty hack (in this case).
 
-```python
+```{testcode}
 from pypdf import PaperSize, PdfReader, PdfWriter, Transformation
 
 # Read source file
@@ -265,7 +265,7 @@ We need a way to merge a transformed page, *without* modifying the source page.
 - we no longer need the media box hack of our first try;
 - transformations are only applied *once*.
 
-```python
+```{testcode}
 from pypdf import PaperSize, PdfReader, PdfWriter, Transformation
 
 # Read source file

docs/user/encryption-decryption.md

@@ -18,7 +18,7 @@ for installing the extra dependencies if interacting with PDFs that use AES.
 
 You can encrypt a PDF by using a password:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 
 reader = PdfReader("example.pdf")
@@ -44,7 +44,7 @@ Since `RC4` is insecure, you should use `AES` algorithms.
 
 You can decrypt a PDF using the appropriate password:
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 
 reader = PdfReader("encrypted-pdf.pdf")

docs/user/extract-images.md

@@ -8,7 +8,7 @@ dependencies, see [installation guide](installation.md).
 Every page of a PDF document can contain an arbitrary number of images.
 The names of the files may not be unique.
 
-```python
+```{testcode}
 from pypdf import PdfReader
 
 reader = PdfReader("example.pdf")
@@ -29,7 +29,7 @@ For example, this document contains such stamps:
 
 You can extract the image from the annotation with the following code:
 
-```python
+```{testcode}
 from pypdf import PdfReader
 
 reader = PdfReader("test_stamp.pdf")

docs/user/extract-text.md

@@ -2,7 +2,7 @@
 
 You can extract text from a PDF:
 
-```python
+```{testcode}
 from pypdf import PdfReader
 
 reader = PdfReader("example.pdf")
@@ -81,7 +81,7 @@ operator, operand-arguments, current transformation matrix, and text matrix.
 
 The following example reads the text of page four of [this PDF document](https://github.com/py-pdf/pypdf/blob/main/resources/GeoBase_NHNC1_Data_Model_UML_EN.pdf), but ignores the header (y > 720) and footer (y < 50).
 
-```python
+```{testcode}
 from pypdf import PdfReader
 
 reader = PdfReader("GeoBase_NHNC1_Data_Model_UML_EN.pdf")
@@ -109,7 +109,7 @@ an [SVG file](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics).
 
 Such an SVG export may help to understand what is going on in a page.
 
-```python
+```{testcode}
 from pypdf import PdfReader
 import svgwrite
 

docs/user/file-size.md

@@ -28,7 +28,7 @@ reduction (from 5.7 MB to 0.8 MB) within a real PDF.
 ## Removing Images
 
 
-```python
+```{testcode}
 from pypdf import PdfWriter
 
 writer = PdfWriter(clone_from="example.pdf")
@@ -45,7 +45,7 @@ If we reduce the quality of the images within the PDF, we can **sometimes**
 reduce the file size of the PDF overall. That depends on how well the reduced
 quality image can be compressed.
 
-```python
+```{testcode}
 from pypdf import PdfWriter
 
 writer = PdfWriter(clone_from="example.pdf")
@@ -67,7 +67,7 @@ the same.
 Deflate compression can be applied to a page via
 {meth}`page.compress_content_streams <pypdf._page.PageObject.compress_content_streams>`:
 
-```python
+```{testcode}
 from pypdf import PdfWriter
 
 writer = PdfWriter(clone_from="example.pdf")

docs/user/forms.md

@@ -2,7 +2,7 @@
 
 ## Reading form fields
 
-```python
+```{testcode}
 from pypdf import PdfReader
 
 reader = PdfReader("form.pdf")
@@ -15,7 +15,7 @@ fields = reader.get_fields()
 
 ## Filling out forms
 
-```python
+```{testcode}
 from pypdf import PdfReader, PdfWriter
 
 reader = PdfReader("form.pdf")
@@ -71,14 +71,14 @@ To flesh out this overview:
 
 In _pypdf_ fields are extracted from the `/Fields` array:
 
-```python
+```{testcode}
 from pypdf import PdfReader
 
 reader = PdfReader("form.pdf")
 fields = reader.get_fields()
 ```
 
-```python
+```{testcode}
 from pypdf import PdfReader
 from pypdf.constants import AnnotationDictionaryAttributes