docs: Describe examples (#2262)

* Update .py examples with clearer guidance,
update out of date imports and calls

Signed-off-by: Mingxuan Zhao <43148277+mingxzhao@users.noreply.github.com>

* Fix minimal.py string error, fix ruff format error

Signed-off-by: Mingxuan Zhao <43148277+mingxzhao@users.noreply.github.com>

* fix more CI issues

Signed-off-by: Mingxuan Zhao <43148277+mingxzhao@users.noreply.github.com>

---------

Signed-off-by: Mingxuan Zhao <43148277+mingxzhao@users.noreply.github.com>

docs/examples/translate.py

@@ -1,3 +1,23 @@
+# %% [markdown]
+# Translate extracted text content and regenerate Markdown with embedded images.
+#
+# What this example does
+# - Converts a PDF and saves original Markdown with embedded images.
+# - Translates text elements and table cell contents, then saves a translated Markdown.
+#
+# Prerequisites
+# - Install Docling. Add a translation library of your choice inside `translate()`.
+#
+# How to run
+# - From the repo root: `python docs/examples/translate.py`.
+# - The script writes original and translated Markdown to `scratch/`.
+#
+# Notes
+# - `translate()` is a placeholder; integrate your preferred translation API/client.
+# - Image generation is enabled to preserve embedded images in the output.
+
+# %%
+
 import logging
 from pathlib import Path
 
@@ -32,7 +52,7 @@ def main():
 
     data_folder = Path(__file__).parent / "../../tests/data"
     input_doc_path = data_folder / "pdf/2206.01062.pdf"
-    output_dir = Path("scratch")
+    output_dir = Path("scratch")  # ensure this directory exists before saving
 
     # Important: For operating with page images, we must keep them, otherwise the DocumentConverter
     # will destroy them for cleaning up memory.
@@ -56,6 +76,7 @@ def main():
     doc_filename = conv_res.input.file.name
 
     # Save markdown with embedded pictures in original text
+    # Tip: create the `scratch/` folder first or adjust `output_dir`.
     md_filename = output_dir / f"{doc_filename}-with-images-orig.md"
     conv_doc.save_as_markdown(md_filename, image_mode=ImageRefMode.EMBEDDED)