Skip to content

Commit d5bd87f

Browse files
afrendeiroafrendeiro
committed
build with github actions
1 parent a7a7bdb commit d5bd87f

File tree

3 files changed

+111
-39
lines changed

3 files changed

+111
-39
lines changed

‎.github/workflows/build.yml

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
name: Build Lab Manual
2+
3+
on:
4+
push:
5+
branches:
6+
- "*"
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v3
15+
16+
- name: Install dependencies
17+
run: |
18+
sudo apt-get update
19+
sudo apt-get install -y pandoc wkhtmltopdf xfonts-75dpi
20+
python3 -m pip install --user pipx
21+
python3 -m pipx ensurepath
22+
pipx install mdformat
23+
pipx inject mdformat mdformat-gfm
24+
25+
- name: Set version in metadata.yaml
26+
run: |
27+
VERSION=$(git describe --tags --always --dirty || echo "dev")
28+
sed -i -e "s/<VERSION>/$VERSION/g" metadata.yaml
29+
30+
- name: Create ORDER file
31+
run: |
32+
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
33+
34+
- name: Format markdown files
35+
run: |
36+
find source -type f -name "*.md" | xargs mdformat
37+
38+
- name: Add modifications to files
39+
run: |
40+
readarray -t ORDER < ORDER
41+
echo ${ORDER[@]:0:12} | xargs sed -i -e '$a\\n'
42+
echo ${ORDER[@]:0:12} | xargs sed -i -e '$a<div style="page-break-after: always;"></div>'
43+
44+
- name: Convert to HTML
45+
run: |
46+
mkdir -p build/{html,pdf}
47+
cat ORDER | xargs pandoc \
48+
-V toc-title='Table of contents' \
49+
--embed-resources \
50+
--standalone \
51+
--css=assets/style.css \
52+
--toc \
53+
--toc-depth 1 \
54+
-t html5 \
55+
--metadata-file=metadata.yaml \
56+
-o build/html/rendeiro-lab_manual.html
57+
58+
- name: Convert to PDF
59+
run: |
60+
wkhtmltopdf \
61+
--enable-internal-links \
62+
--enable-local-file-access \
63+
--header-center "Rendeiro lab manual" \
64+
--header-font-size 8 \
65+
--footer-center "[page]/[topage]" \
66+
--footer-font-size 8 \
67+
build/html/rendeiro-lab_manual.html \
68+
build/pdf/rendeiro-lab_manual.pdf
69+
70+
- name: Upload Pages artifact
71+
uses: actions/upload-pages-artifact@v1
72+
with:
73+
path: build/html
74+
75+
deploy:
76+
needs: build
77+
runs-on: ubuntu-latest
78+
permissions:
79+
pages: write
80+
id-token: write
81+
environment:
82+
name: github-pages
83+
url: ${{ steps.deployment.outputs.page_url }}
84+
steps:
85+
- name: Deploy to GitHub Pages
86+
id: deployment
87+
uses: actions/deploy-pages@v1

‎CHANGELOG.md

+5
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
## Unreleased
44

5+
- Build with github actions
6+
- Improve README
7+
8+
## 2025-01-27
9+
510
- Add todo section to the README.md
611
- Add page on offboarding
712
- Decouple manual from how to-style documents, or incorporate them in manual

‎README.md

+19-39
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,43 @@
11
<div style="page-break-after: always;"></div>
22

33
# Lab manual
4-
<!--
5-
<div style="width:50%; display: block; margin: auto;">
6-
<img src="https://github.com/rendeirolab/lab-manual/blob/main/assets/img/logo.png?raw=true" style="width: 100%;"/>
7-
<p style="text-align: center;">Rendeiro Lab</p>
8-
</div> -->
94

10-
This is the Rendeiro lab manual, with all the information about the lab's culture and procedures.
5+
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.
116

12-
The manual is available in the [`lab-manual`](https://github.com/rendeirolab/lab-manual/tree/main/manual) repository on Github.
7+
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/).
138

14-
It is written in [Markdown](https://daringfireball.net/projects/markdown/), but can be converted to HTML and PDF using [Pandoc](https://pandoc.org/).
15-
16-
It can be maintained and edited by anyone on Github.
9+
This manual is open source and maintained collaboratively. Anyone on GitHub can propose changes.
1710

1811
## Building the manual
1912

20-
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).
21-
22-
Converting the manual to a single HTML file:
13+
The project includes a [Makefile](https://github.com/rendeirolab/lab-manual/blob/main/Makefile) to streamline the development process.
2314

24-
```bash
25-
pandoc \
26-
--toc \
27-
--metadata-file=metadata.yaml \
28-
--css style.css \
29-
-s README.md manual/*.md \
30-
-o rendeiro-lab_manual.html
31-
```
15+
Key targets include:
16+
- **`format`**: Formats Markdown files consistently using `mdformat`.
17+
- **`build`**: Converts the manual into a single HTML file using `pandoc` and generates a PDF file using `wkhtmltopdf`.
18+
- **`clean`**: Removes generated files to ensure a fresh build.
3219

33-
Converting the manual to a single PDF file (requires wkhtmltopdf dependency):
34-
35-
```bash
36-
pandoc \
37-
--toc \
38-
-f gfm -t html5 \
39-
--metadata-file=metadata.yaml \
40-
--css https://raw.githubusercontent.com/simov/markdown-viewer/master/themes/github.css \
41-
-s README.md manual/*.md \
42-
-o rendeiro-lab_manual.pdf
43-
```
20+
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.
4421

4522
## Editing content
4623

47-
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.
24+
To contribute:
25+
1. Edit or create files directly on GitHub or locally on your system.
26+
2. Submit a pull request with a clear, one-line description of the changes made.
27+
3. Follow best practices by adding reviewers and referencing related issues, if applicable.
28+
29+
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.
4830

49-
To add a table of contents to each document, use [mdformat-toc](https://github.com/hukkin/mdformat-toc).
50-
Simply add `<!-- mdformat-toc start -->` to the desired location of the document, and run `mdformat <file.md>` to generate it.
31+
## Acknowledgements
5132

52-
## Sources of inspiration
33+
We thank the following labs for sharing their open-source lab manuals, which inspired this project:
5334

54-
- https://github.com/alylab/labmanual
55-
- https://github.com/getzlab/getzlab.github.io
35+
- [Aly Lab Manual](https://github.com/alylab/labmanual)
36+
- [Getz Lab Manual](https://github.com/getzlab/getzlab.github.io)
5637

5738

5839
## TODO
5940

60-
- [ ] Github actions build + deploy
6141
- [ ] Add instructions on how to version manual
6242
- [ ] Add to lab website
6343
- [ ] Improve and include [public data page](source/public_data.md)

0 commit comments

Comments
 (0)