Merge pull request jupyter-book#93 from ExecutableBookProject/tests

adding PDF tests with HTML and some docs

.github/workflows/pyppeteer_reqs.txt

@@ -0,0 +1,39 @@
+gconf-service
+libasound2
+libatk1.0-0
+libatk-bridge2.0-0
+libc6
+libcairo2
+libcups2
+libdbus-1-3
+libexpat1
+libfontconfig1
+libgcc1
+libgconf-2-4
+libgdk-pixbuf2.0-0
+libglib2.0-0
+libgtk-3-0
+libnspr4
+libpango-1.0-0
+libpangocairo-1.0-0
+libstdc++6
+libx11-6
+libx11-xcb1
+libxcb1
+libxcomposite1
+libxcursor1
+libxdamage1
+libxext6
+libxfixes3
+libxi6
+libxrandr2
+libxrender1
+libxss1
+libxtst6
+ca-certificates
+fonts-liberation
+libappindicator1
+libnss3
+lsb-release
+xdg-utils
+wget

.github/workflows/tests.yml

@@ -46,6 +46,11 @@ jobs:
         python -m pip install --upgrade pip
         pip install -e .[testing]
 
+    - name: Install Headless Chrome dependencies
+      run: |
+        sudo apt-get install -yq $(cat .github/workflows/pyppeteer_reqs.txt)
+
+
     # Tests
     - name: Run pytest
       run: |

docs/use/pdf.md

@@ -17,18 +17,25 @@ it as a PDF by emulating a browser from the command-line.
 This is an experimental feature, and may change in the future.
 ```
 
-````{sidebar} **Note**
+### Installing pyppeteer
+
 If you wish to build a PDF from your book's HTML, you will need the `pyppeteer` package.
 You can install it like so:
 
 ```
 pip install pyppeteer
 ```
 
+You may also need to install this bundle of packages below (on *nix systems):
+
+```{literalinclude} ../../.github/workflows/pyppeteer_reqs.txt
+```
+
+```{sidebar}
 In addition, if you get errors about libraries that don't exist, check out
 [these install commands](https://circleci.com/orbs/registry/orb/threetreeslight/puppeteer)
 to see if that fixes it. We warned you it was an experimental feature :-)
-````
+```
 
 To build a single PDF from your book's HTML, use the following command:
 

jupyter_book/pdf.py

@@ -2,6 +2,8 @@
 from pathlib import Path
 import asyncio
 
+from .utils import _error
+
 
 def html_to_pdf(html_file, pdf_file):
     """
@@ -21,11 +23,10 @@ async def _html_to_pdf(html_file, pdf_file):
     try:
         from pyppeteer import launch
     except ImportError:
-        raise ImportError(
-            (
-                "Generating PDF from book HTML requires the pyppetteer package."
-                "Install it first."
-            )
+        _error(
+            "Generating PDF from book HTML requires the pyppetteer package. "
+            "Install it first.",
+            ImportError,
         )
     browser = await launch(args=["--no-sandbox"])
     page = await browser.newPage()

jupyter_book/tests/test_pdf.py

@@ -0,0 +1,17 @@
+"""Testing PDF functionality of the CLI."""
+
+from pathlib import Path
+from subprocess import run
+
+path_tests = Path(__file__).parent
+
+
+def test_html_pdf(tmpdir):
+    path_output = Path(tmpdir).absolute()
+    path_template = path_tests.parent.joinpath("book_template")
+    cmd = f"jb build {path_template} --path-output {path_output} --build pdf_html"
+    run(cmd.split(), check=True)
+    path_html = path_output.joinpath("_build", "html")
+    path_pdf = path_output.joinpath("_build", "pdf")
+    assert path_html.joinpath("index.html").exists()
+    assert path_pdf.joinpath("book.pdf").exists()

jupyter_book/utils.py

@@ -57,6 +57,8 @@ def _message_box(msg, color="green", doprint=True):
     return box
 
 
-def _error(msg):
+def _error(msg, kind=None):
+    if kind is None:
+        kind = ValueError
     box = _message_box(msg, color="red", doprint=False)
-    raise ValueError(box)
+    raise kind(box)

setup.py

@@ -79,6 +79,7 @@
             "plotly",
             "bokeh",
             "altair",
+            "pyppeteer",
         ],
         "pdf_html": "pyppeteer",
     },