build with github actions

Author: afrendeiro

.github/workflows/build.yml

@@ -0,0 +1,87 @@
+name: Build Lab Manual
+
+on:
+  push:
+    branches:
+      - "*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y pandoc wkhtmltopdf xfonts-75dpi
+        python3 -m pip install --user pipx
+        python3 -m pipx ensurepath
+        pipx install mdformat
+        pipx inject mdformat mdformat-gfm
+
+    - name: Set version in metadata.yaml
+      run: |
+        VERSION=$(git describe --tags --always --dirty || echo "dev")
+        sed -i -e "s/<VERSION>/$VERSION/g" metadata.yaml
+
+    - name: Create ORDER file
+      run: |
+        echo "README.md source/getting_started.md source/mission_statement.md source/code_of_conduct.md source/communication_and_meetings.md source/infrastructure.md source/project_planning.md source/research.md source/record_keeping.md source/learning.md source/manuscript_writing.md source/offboarding.md CHANGELOG.md" > ORDER
+
+    - name: Format markdown files
+      run: |
+        find source -type f -name "*.md" | xargs mdformat
+
+    - name: Add modifications to files
+      run: |
+        readarray -t ORDER < ORDER
+        echo ${ORDER[@]:0:12} | xargs sed -i -e '$a\\n'
+        echo ${ORDER[@]:0:12} | xargs sed -i -e '$a<div style="page-break-after: always;"></div>'
+
+    - name: Convert to HTML
+      run: |
+        mkdir -p build/{html,pdf}
+        cat ORDER | xargs pandoc \
+            -V toc-title='Table of contents' \
+            --embed-resources \
+            --standalone \
+            --css=assets/style.css \
+            --toc \
+            --toc-depth 1 \
+            -t html5 \
+            --metadata-file=metadata.yaml \
+            -o build/html/rendeiro-lab_manual.html
+
+    - name: Convert to PDF
+      run: |
+        wkhtmltopdf \
+            --enable-internal-links \
+            --enable-local-file-access \
+            --header-center "Rendeiro lab manual" \
+            --header-font-size 8 \
+            --footer-center "[page]/[topage]" \
+            --footer-font-size 8 \
+            build/html/rendeiro-lab_manual.html \
+            build/pdf/rendeiro-lab_manual.pdf
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Build with github actions
+
+## 2025-01-27
+
 - Add todo section to the README.md
 - Add page on offboarding
 - Decouple manual from how to-style documents, or incorporate them in manual

README.md

@@ -1,11 +1,6 @@
 <div style="page-break-after: always;"></div>
 
 # Lab manual
-<!--
-<div style="width:50%; display: block; margin: auto;">
-    <img src="https://github.com/rendeirolab/lab-manual/blob/main/assets/img/logo.png?raw=true" style="width: 100%;"/>
-    <p style="text-align: center;">Rendeiro Lab</p>
-</div> -->
 
 This is the Rendeiro lab manual, with all the information about the lab's culture and procedures.
 
@@ -17,30 +12,11 @@ It can be maintained and edited by anyone on Github.
 
 ## Building the manual
 
-A [Makefile](https://github.com/rendeirolab/lab-manual/blob/main/manual/Makefile) is available in the [`lab-manual repository`](https://github.com/rendeirolab/lab-manual/tree/main/manual).
+A [Makefile](https://github.com/rendeirolab/lab-manual/blob/main/Makefile) is available to manage the development process.
 
-Converting the manual to a single HTML file:
+The `build` target, converts the manual to a single HTML file using pandoc, and `wkhtmltopdf` is used to make a PDF file.
 
-```bash
-pandoc \
-    --toc \
-    --metadata-file=metadata.yaml \
-    --css style.css \
-    -s README.md manual/*.md \
-    -o rendeiro-lab_manual.html
-```
-
-Converting the manual to a single PDF file (requires wkhtmltopdf dependency):
-
-```bash
-pandoc \
-    --toc \
-    -f gfm -t html5 \
-    --metadata-file=metadata.yaml \
-    --css https://raw.githubusercontent.com/simov/markdown-viewer/master/themes/github.css \
-    -s README.md manual/*.md \
-    -o rendeiro-lab_manual.pdf
-```
+A custom [CSS file](assets/style.css) is used for styling.
 
 ## Editing content
 
@@ -57,7 +33,6 @@ Simply add `<!-- mdformat-toc start -->` to the desired location of the document
 
 ## TODO
 
-- [ ] Github actions build + deploy
 - [ ] Add instructions on how to version manual
 - [ ] Add to lab website
 - [ ] Improve and include [public data page](source/public_data.md)