✨ Added PDF building

.github/workflows/build_docs.yaml

@@ -28,10 +28,7 @@ jobs:
           pip install -r requirements.txt
       - name: Build latest documentation
         shell: bash
-        run: |
-          make clean
-          make
-          cp docs/index.html _build
+        run: ./build_docs.sh
       - name: Deploy documentation to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@5dc1d5a192aeb5ab5b7d5a77b7d36aea4a7f5c92 # This is version 4.1.4
         with:

.gitignore

@@ -18,6 +18,7 @@ ch03tests/diffusion/.coverage
 ch03tests/diffusion/.pytest_cache
 ch03tests/diffusion/htmlcov
 ch03tests/DiffusionExample/.pytest_cache
+ch04packaging/.pytest_cache
 ch04packaging/greeter.py
 ch04packaging/greetings/dist/Greetings*.egg
 ch04packaging/greetings/doc/output/

Makefile

@@ -12,6 +12,9 @@ index.md:
 html: _config.yml _toc.yml index.md
 	jupyter-book build --verbose --keep-going .
 
+pdf: _config.yml _toc.yml index.md
+	jupyter-book build --builder pdfhtml --verbose --keep-going .
+
 clean:
 	rm -f _config.yml
 	rm -f _toc.yml
@@ -31,15 +34,14 @@ clean:
 	rm -f ch07dry/*.yaml
 	rm -f index.html
 	rm -f index.md
-	rm -f notes.pdf
-	rm -f notes.tex
 	rm -rf _build
 	rm -rf ch*/__pycache__
 	rm -rf ch*/*/__pycache__
 	rm -rf ch*/*/*/__pycache__
 	rm -rf ch*/*/*/*/__pycache__
 	rm -rf ch03tests/diffusion/.pytest_cache
 	rm -rf ch03tests/DiffusionExample/.pytest_cache
+	rm -rf ch04packaging/.pytest_cache
 	rm -rf ch04packaging/greetings/doc/output/
 	rm -rf ch09*/*.csv
 	rm -rf ch09*/*.db

build_docs.sh

@@ -0,0 +1,10 @@
+#! /bin/bash
+
+# Build the PDF notes and cleanup the single-page HTML output
+make clean
+make pdf
+jupyter-book clean --html .
+
+# Build the HTML output and link the redirect page
+make html
+cp docs/index.html _build

docs/_config.yml

@@ -1,6 +1,25 @@
-title: "Research Software Engineering with Python"
+#######################################################################################
+# Book settings
+title: Research Software Engineering with Python
 author: The Alan Turing Institute
 logo: docs/ATI_logo_black_W1024px.png
 only_build_toc_files: true
+
+#######################################################################################
+# Execution settings
 execute:
-  execute_notebooks: cache
+  execute_notebooks: force
+
+#######################################################################################
+# HTML-specific settings
+html:
+  favicon: docs/favicon.ico
+  use_repository_button: true
+  use_issues_button: true
+  use_edit_page_button: true
+  extra_navbar: <p>Download notes as <a href="/pdf/book.pdf">PDF</a>.</p><p>Powered by <a href="https://jupyterbook.org">Jupyter Book</a>.</p>
+
+#######################################################################################
+# Git repository settings
+repository:
+  url: https://github.com/alan-turing-institute/rsd-engineeringcourse

docs/index.md

@@ -25,8 +25,6 @@ None: you are not graded. You will be provided with 2 exercises for self-assessm
 
 ## Versions
 
-You can find the course notes as HTML via the navigation bar to the left.
-
-The [notes](notes.pdf) are also available in a printable pdf format.
+You can browse through course notes as HTML or download them as a printable PDF via the navigation bar to the left.
 
 **If you encounter any problem or bug in these materials**, please remember to add an issue to the [course repo](https://github.com/alan-turing-institute/rsd-engineeringcourse), explaining the problem and, potentially, its solution. In this way we can improve the instructions for future users.

requirements.txt

@@ -15,6 +15,7 @@ pandas==1.3.1
 ply==3.11
 pycodestyle==2.7.0
 pylint==2.9.6
+pyppeteer==0.2.5
 pytest-cov==2.12.1
 pytest==6.2.4
 PyYAML==5.4.1