Add automated workflow publishing capabilities

.github/workflows/deploy-book.yml

@@ -0,0 +1,34 @@
+# deploys the software gardening almanac content through
+# GH Pages using Jupyter Book publishing tools.
+---
+name: deploy book
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install python env
+        uses: ./.github/actions/install-python-env
+      - name: Build the jupyter book content
+        run: |
+          poetry run poe build-book
+      - name: Build a PDF from the HTML content
+        run: |
+          poetry run poe build-book-pdf
+      - name: Copy and rename the PDF to the HTML dir
+        run: |
+          cp src/almanac/_build/pdf/book.pdf \
+          src/almanac/_build/html/software-gardening-almanac.pdf
+      - name: Deploy book to GH Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: src/almanac/_build/html

.pre-commit-config.yaml

@@ -12,6 +12,10 @@ repos:
       - id: check-added-large-files
       - id: check-toml
       - id: detect-private-key
+  - repo: https://github.com/python-poetry/poetry
+    rev: "1.5.1"
+    hooks:
+      - id: poetry-check
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6
     hooks:

README.md

@@ -2,6 +2,11 @@
 
 An open-source handbook of applied guidance and tools for sustainable software development and maintenance.
 
+Please see the following links to access published content:
+
+- __Online (HTML)__: https://software-gardening.github.io/almanac/
+- __Offline (PDF)__: [software-gardening-almanac.pdf](https://software-gardening.github.io/almanac/software-gardening-almanac.pdf)
+
 ## CONTRIBUTING
 
 Please see our [`CONTRIBUTING.md`](CONTRIBUTING.md) document for more information on how to contribute to this project.

pyproject.toml

@@ -16,6 +16,7 @@ pytest = "^8.1.1"
 cffconvert = "^2.0.0"
 linkchecker = "^10.4.0"
 vale = "^3.3.1.0"
+pyppeteer = "^2.0.0"
 
 [tool.isort]
 profile = "black"
@@ -29,6 +30,10 @@ exclude_dirs = ["tests"]
 build-book.shell = """
   jupyter-book build src/almanac
 """
+# build a PDF from the HTML content
+build-book-pdf.shell = """
+  jupyter-book build src/almanac --builder pdfhtml
+"""
 # builds the jupyter book related to this project and opens a new browser window
 build-book-dev.shell = """
   jupyter-book build src/almanac && \

src/almanac/_config.yml

@@ -3,8 +3,7 @@
 # Book settings
 title: The Software Gardening Almanac
 author: The Software Gardening Community
-logo: |
-  "https://raw.githubusercontent.com/software-gardening/brand/main/logo/logo.png"
+logo: assets/software-gardening-logo.png
 
 #######################################################################################
 # Execution settings

src/almanac/_static/custom.css

@@ -1,3 +1,13 @@
 .navbar-brand img {
     max-width:60%;
 }
+
+@media print
+{
+    /* Removes "skip to main content" from pdf output.
+    Reference: https://github.com/executablebooks/jupyter-book/issues/2045
+    and https://github.com/pydata/pydata-sphinx-theme/issues/1745 */
+    .skip-link {
+        display: none;
+    }
+}

src/almanac/_toc.yml

@@ -3,8 +3,6 @@ format: jb-book
 root: introduction.md
 parts:
   - chapters:
-      - title: Preface
-        file: preface.md
       - title: Garden Circle
         file: garden-circle/garden-circle.md
         sections: