Skip to content

Commit 6d4562c

Browse files
mirpedrolmirpedrol
authored
Merge pull request #48 from mirpedrol/add-mkdocs
add mkdocs pages
2 parents 48ef4ec + 6d60263 commit 6d4562c

File tree

10 files changed

+275
-41
lines changed

10 files changed

+275
-41
lines changed

‎.github/workflows/build-docs.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: build docs
2+
on:
3+
push:
4+
branches:
5+
- master
6+
- main
7+
- dev
8+
permissions:
9+
contents: write
10+
jobs:
11+
deploy:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v3
15+
- uses: actions/setup-python@v4
16+
with:
17+
python-version: 3.x
18+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
19+
- uses: actions/cache@v3
20+
with:
21+
key: mkdocs-material-${{ env.cache_id }}
22+
path: .cache
23+
restore-keys: |
24+
mkdocs-material-
25+
- run: pip install mkdocs-material
26+
- run: mkdocs gh-deploy --force

‎.gitignore

+5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
# Docs / other
2+
.cache/
3+
.DS_Store
4+
15
# Ignore Gradle project-specific cache directory
26
.gradle
37
.idea
@@ -8,3 +12,4 @@ build
812
work
913
out
1014
co2footprint-*.txt
15+
site

‎README.md

+6-37
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
A Nextflow plugin to estimate the CO<sub>2</sub> footprint of pipeline runs.
44

5+
## 📚 Docs 👉🏻 <https://nextflow-io.github.io/nf-co2footprint>
6+
57
## Introduction
68

79
The nf-co2footprint plugin estimates the energy consumption for each pipeline task based on the Nextflow resource usage metrics and information about the power consumption of the underlying compute system.
@@ -19,16 +21,6 @@ developed in the Green Algorithms project: www.green-algorithms.org
1921
The nf-co2footprint plugin generates a detailed TXT carbon footprint report containing the energy consumption, the estimated CO<sub>2</sub> emission and other relevant metrics for each task.
2022
Additionally, an HTML report is generated with information about the carbon footprint of the whole pipeline run and containing plots showing, for instance, an overview of the CO<sub>2</sub> emissions for the different processes.
2123

22-
23-
## Testing the plugin prior release
24-
25-
The plugin can be tested prior release without using a local Nextflow build using the following steps:
26-
27-
1. Build the plugin: `make buildPlugins`
28-
2. Copy `build/plugins/nf-co2footprint-<version>` to `$HOME/.nextflow/plugins`
29-
30-
The details on how to build and test the plugin during development using a local Nextflow build you can find in the [nf-hello README](https://github.com/nextflow-io/nf-hello/tree/master#readme).
31-
3224
## Quick Start
3325

3426
Declare the plugin in your Nextflow pipeline configuration file:
@@ -38,36 +30,13 @@ plugins {
3830
id '[email protected]'
3931
}
4032
```
41-
<!-- NOTE: currently seems to only work with pinned version -->
42-
43-
This is all that is needed.
44-
<!-- - Nextflow will automatically fetch the plugin code at run time. -->
45-
46-
## Customising parameters
47-
48-
You can adjust the nf-co2footprint plugin parameters in your config file as follows:
49-
50-
```groovy title="nextflow.config"
51-
co2footprint {
52-
file = "${params.outdir}/co2footprint.txt"
53-
reportFile = "${params.outdir}/co2footprint_report.html"
54-
ci = 300
55-
pue = 1.4
56-
}
57-
```
5833

59-
Include the config file for your pipeline run using the `-c` Nextflow parameter, for example as follows:
34+
This is all that is needed. Run your pipeline with the usual command.
6035

61-
```bash
62-
nextflow run nextflow-io/hello -c nextflow.config
63-
```
36+
You can find more information on plugins in the [Nextflow documentation](https://www.nextflow.io/docs/latest/plugins.html#plugins).
6437

65-
The following parameters are currently available:
66-
- `file`: Name of the TXT carbon footprint report containing the energy consumption, the estimated CO<sub>2</sub> emission and other relevant metrics for each task.
67-
- `reportFile`: Name of the HTML report containing information about the entire carbon footprint, overview plots and more detailed task-specific metrics.
68-
- `ci`: carbon intensity of the respective energy production.
69-
- `pue`: power usage effectiveness, efficiency coefficient of the data centre.
70-
- `powerdrawMem`: power draw from memory.
38+
> [!NOTE]
39+
> To test the plugin prior to its first release, refer to the [contributing documentation](contributing/setup.md).
7140
7241
## Credits
7342

‎docs/co2footprint.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: CO2footprint-measures
3+
description: Definition of CO2 footprint
4+
hide:
5+
- toc
6+
---
7+
8+
# CO2e Footprint Measures
9+
10+
A CO<sub>2</sub> equivalent (CO<sub>2</sub>e) is a metric used to compare the emissions from various greenhouse gases based on their impact on global warming.
11+
12+
For this, the amounts of other gases are converted to the amount of CO<sub>2</sub> that would have the same impact on global warming (over a 100-year period).
13+
14+
The equation used for the calculation of the carbon footprint ($C$) is:
15+
16+
$C = t * (n_c * P_c * u_c + n_m * P_m) * PUE * CI$
17+
18+
Being:
19+
20+
- **$t$** the running time of the computation (h)
21+
- **$n_c$** the number of cores
22+
- **$n_m$** the size of memory available (GB)
23+
- **$u_c$** the core usage factor (between 0 and 1)
24+
- **$P_c$** the power draw of a computing core (W)
25+
- **$P_m$** the power draw of memory (W, per GB)
26+
- **$PUE$** the efficiency coefficient of the data centre
27+
- **$CI$** the carbon intensity of energy production, which represents carbon footprint of producing 1 kWh of energy for a given country and energy mix.
28+
29+
## References
30+
31+
> **Green Algorithms: Quantifying the Carbon Footprint of Computation.**
32+
>
33+
> Lannelongue, L., Grealey, J., Inouye, M.,
34+
>
35+
> Adv. Sci. 2021, 2100707. https://doi.org/10.1002/advs.202100707

‎docs/contributing/setup.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Contribution instructions
3+
description: How to contribute to nf-co2footprint
4+
---
5+
6+
# Getting started with plugin development
7+
8+
## Compiling
9+
10+
To compile and run the tests use the following command:
11+
12+
```bash
13+
./gradlew check
14+
```
15+
16+
## Launch without a local Nextflow build
17+
18+
The plugin can be tested prior release without using a local Nextflow build using the following steps:
19+
20+
1. Build the plugin:
21+
```bash
22+
make buildPlugins
23+
2. Copy `build/plugins/nf-co2footprint-<version>` to `$HOME/.nextflow/plugins`
24+
4. Run nextflow with this command:
25+
26+
```bash
27+
./launch.sh run -plugins [email protected] <script/pipeline name> [pipeline params]
28+
```
29+
30+
## Launch it with Nextflow
31+
32+
To test with Nextflow for development purpose:
33+
34+
1. Clone the Nextflow repo into a sibling directory
35+
36+
```bash
37+
cd .. && https://github.com/nextflow-io/nextflow
38+
cd nextflow && ./gradlew exportClasspath
39+
```
40+
41+
2. Append the following line to the `settings.gradle` in this project:
42+
43+
```bash
44+
includeBuild('../nextflow')
45+
```
46+
47+
3. Compile the plugin code
48+
49+
```bash
50+
./gradlew compileGroovy
51+
```
52+
53+
4. Run nextflow with this command:
54+
55+
```bash
56+
./launch.sh run -plugins nf-co2footprint <script/pipeline name> [pipeline params]
57+
```
58+
59+
## Change and preview the docs
60+
61+
The docs are generated using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). To change the docs, edit the files in the [docs/](docs/) folder and run the following command to generate the docs (after installing mkdocs via `pip install mkdocs-material`):
62+
63+
```bash
64+
mkdocs serve
65+
```
66+
67+
To preview the docs, open the URL provided by mkdocs in your browser.

‎docs/index.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: nf-co2footprint
3+
description: Nextflow plugin for CO2 footprint estimations
4+
---
5+
6+
# nf-co2footprint
7+
8+
{==
9+
10+
**A Nextflow plugin to estimate the CO<sub>2</sub> footprint of pipeline runs.**
11+
12+
==}
13+
14+
--8<-- "README.md:6:"

‎docs/javascripts/katex.js

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
document$.subscribe(({ body }) => {
2+
renderMathInElement(body, {
3+
delimiters: [
4+
{ left: "$$", right: "$$", display: true },
5+
{ left: "$", right: "$", display: false },
6+
{ left: "\\(", right: "\\)", display: false },
7+
{ left: "\\[", right: "\\]", display: true }
8+
],
9+
})
10+
})

‎docs/usage/parameters.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Parameters
3+
description: Customising parameters for the CO2e calculation.
4+
---
5+
6+
## Customising parameters
7+
8+
You can adjust the nf-co2footprint plugin parameters in your config file as follows:
9+
10+
```groovy title="nextflow.config"
11+
co2footprint {
12+
file = "${params.outdir}/co2footprint.txt"
13+
reportFile = "${params.outdir}/co2footprint_report.html"
14+
ci = 300
15+
pue = 1.4
16+
}
17+
```
18+
19+
Include the config file for your pipeline run using the `-c` Nextflow parameter, for example as follows:
20+
21+
```bash
22+
nextflow run nextflow-io/hello -c nextflow.config
23+
```
24+
25+
The following parameters are currently available:
26+
27+
- `file`: Name of the TXT carbon footprint report containing the energy consumption, the estimated CO<sub>2</sub> emission and other relevant metrics for each task.
28+
- `reportFile`: Name of the HTML report containing information about the entire carbon footprint, overview plots and more detailed task-specific metrics.
29+
- `ci`: carbon intensity of the respective energy production.
30+
- `pue`: power usage effectiveness, efficiency coefficient of the data centre.
31+
- `powerdrawMem`: power draw from memory.

‎mkdocs.yml

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
site_name: nf-co2footprint
2+
repo_name: nextflow-io/nf-co2footprint
3+
repo_url: https://github.com/nextflow-io/nf-co2footprint
4+
site_url: https://nextflow-io.github.io/nf-co2footprint/
5+
edit_uri: edit/main/docs/
6+
7+
nav:
8+
- Home:
9+
- index.md
10+
- co2footprint.md
11+
- Usage:
12+
- usage/parameters.md
13+
- Contributing:
14+
- contributing/setup.md
15+
16+
theme:
17+
name: material
18+
icon:
19+
logo: octicons/cloud-16
20+
repo: fontawesome/brands/github
21+
palette:
22+
# Palette toggle for dark mode
23+
- media: "(prefers-color-scheme: dark)"
24+
scheme: slate
25+
primary: green
26+
accent: light green
27+
toggle:
28+
icon: material/weather-sunny
29+
name: Switch to light mode
30+
# Palette toggle for light mode
31+
- media: "(prefers-color-scheme: light)"
32+
scheme: default
33+
primary: green
34+
accent: light green
35+
toggle:
36+
icon: material/weather-night
37+
name: Switch to dark mode
38+
font:
39+
text: Inter
40+
features:
41+
- content.action.edit
42+
- content.code.annotate
43+
- content.code.copy
44+
- navigation.instant
45+
- navigation.top
46+
- navigation.tracking
47+
- navigation.sections
48+
- search.share
49+
- toc.follow
50+
51+
extra_javascript:
52+
- javascripts/katex.js
53+
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
54+
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
55+
56+
extra_css:
57+
- https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
58+
59+
markdown_extensions:
60+
- admonition
61+
- def_list
62+
- md_in_html
63+
- pymdownx.emoji:
64+
emoji_index: !!python/name:materialx.emoji.twemoji
65+
emoji_generator: !!python/name:materialx.emoji.to_svg
66+
- pymdownx.highlight:
67+
anchor_linenums: true
68+
- pymdownx.inlinehilite
69+
- pymdownx.critic
70+
- pymdownx.snippets
71+
- pymdownx.superfences
72+
- pymdownx.tabbed:
73+
alternate_style: true
74+
- pymdownx.details
75+
- pymdownx.tasklist:
76+
custom_checkbox: true
77+
78+
plugins:
79+
- search
80+
- social:
81+
cards: !ENV [CARDS, true]

‎plugins/nf-co2footprint/src/resources/CO2FootprintReportTemplate.html

-4
Original file line numberDiff line numberDiff line change
@@ -192,10 +192,6 @@ <h4>Workflow execution completed unsuccessfully!</h4>
192192

193193
<div class="container">
194194
<h2 id="resources" style="padding-top: 80px;">CO2e Footprint Measures</h2>
195-
<p>These plots give an overview of the distribution of resource usage for each process.
196-
A CO<sub>2</sub> equivalent (CO<sub>2</sub>e) is a metric used to compare the emissions from various greenhouse gases based on their impact on global warming.
197-
For this, the amounts of other gases are converted to the amount of CO<sub>2</sub> that would have the same impact on global warming (over a 100-year period).
198-
</p>
199195

200196
<h4>CO2e</h4>
201197
<ul class="nav nav-tabs" id="co2eplot_tabs" role="tablist">

0 commit comments

Comments
 (0)