build with github actions

rendeirolab · Jan 27, 2025 · ccd7e1e · ccd7e1e
1 parent a7a7bdb
commit ccd7e1e
Show file tree

Hide file tree

Showing 3 changed files with 114 additions and 39 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -0,0 +1,90 @@
+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/index.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/index.html \
+            build/pdf/rendeiro-lab_manual.pdf
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: build/html
+
+    - name: Add CNAME for custom domain
+      run: echo "manual.rendeiro.group" > build/html/CNAME
+
+  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
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Build with github actions
+- Improve README
+
+## 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

diff --git a/README.md b/README.md
@@ -1,63 +1,43 @@
 <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.
+Welcome to the Rendeiro Lab Manual. This manual provides comprehensive information about the lab's culture, procedures, and workflows to ensure a collaborative and efficient research environment.
 
-The manual is available in the [`lab-manual`](https://github.com/rendeirolab/lab-manual/tree/main/manual) repository on Github.
+The manual is hosted in the [`lab-manual`](https://github.com/rendeirolab/lab-manual/tree/main/manual) repository on GitHub. It is written in [Markdown](https://daringfireball.net/projects/markdown/) and can be converted to HTML and PDF using [Pandoc](https://pandoc.org/).
 
-It is written in [Markdown](https://daringfireball.net/projects/markdown/), but can be converted to HTML and PDF using [Pandoc](https://pandoc.org/).
-
-It can be maintained and edited by anyone on Github.
+This manual is open source and maintained collaboratively. Anyone on GitHub can propose changes.
 
 ## 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).
-
-Converting the manual to a single HTML file:
+The project includes a [Makefile](https://github.com/rendeirolab/lab-manual/blob/main/Makefile) to streamline the development process.
 
-```bash
-pandoc \
-    --toc \
-    --metadata-file=metadata.yaml \
-    --css style.css \
-    -s README.md manual/*.md \
-    -o rendeiro-lab_manual.html
-```
+Key targets include:
+- **`format`**: Formats Markdown files consistently using `mdformat`.
+- **`build`**: Converts the manual into a single HTML file using `pandoc` and generates a PDF file using `wkhtmltopdf`.
+- **`clean`**: Removes generated files to ensure a fresh build.
 
-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
-```
+Styling for the manual is controlled by a custom [CSS file](assets/style.css), which ensures a nice appearance in both HTML and PDF formats.
 
 ## Editing content
 
-Edit or create files either directly at Github or locally. Make sure you open a pull request with a brief (one line) description of what the changes are.
+To contribute:
+1. Edit or create files directly on GitHub or locally on your system.
+2. Submit a pull request with a clear, one-line description of the changes made.
+3. Follow best practices by adding reviewers and referencing related issues, if applicable.
+
+For adding a table of contents to any document, use [mdformat-toc](https://github.com/hukkin/mdformat-toc). Insert `<!-- mdformat-toc start -->` where the table of contents should appear, and run `mdformat <file.md>` on the edited file, or `make format` to format all.
 
-To add a table of contents to each document, use [mdformat-toc](https://github.com/hukkin/mdformat-toc).
-Simply add `<!-- mdformat-toc start -->` to the desired location of the document, and run `mdformat <file.md>` to generate it.
+## Acknowledgements
 
-## Sources of inspiration
+We thank the following labs for sharing their open-source lab manuals, which inspired this project:
 
-- https://github.com/alylab/labmanual
-- https://github.com/getzlab/getzlab.github.io
+- [Aly Lab Manual](https://github.com/alylab/labmanual)
+- [Getz Lab Manual](https://github.com/getzlab/getzlab.github.io)
 
 
 ## 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)