fix: add missing template, minor formatting improvements (#36)

* fix: restored triggering catalog generation on push

* fix: re-added missing template, closes #35

* fix: a couple of minor formatting imnprovements, closes #34

* feat: added citation CFF file

* fix: restructured docs to have most information on a single page

Author: m-jahn

.github/workflows/generate.yml

@@ -3,6 +3,8 @@ name: Generate catalog
 on:
   schedule:
     - cron: 0 5 * * 1
+  push:
+    branches: [main, dev]
 
 jobs:
   generate-catalog:

CITATION.cff

@@ -0,0 +1,23 @@
+cff-version: 1.2.0
+message: "If you use this workflow catalog in your research, please cite it using the following metadata."
+title: "Snakemake Workflow Catalog"
+authors:
+  - family-names: "Koester"
+    given-names: "Johannes"
+    orcid: "https://orcid.org/0000-0001-9818-9320"
+  - family-names: "Jahn"
+    given-names: "Michael"
+    orcid: "https://orcid.org/0000-0002-3913-153X"
+abstract: >
+  The Snakemake Workflow Catalog is a collection of standardized workflows
+  for reproducible and scalable data analysis using Snakemake. Workflows
+  are automatically retrieved from Github and tested for compliance.
+repository-code: "https://github.com/snakemake/snakemake-workflow-catalog"
+version: "1.0.0"
+date-released: "2025-03-17"
+keywords:
+  - snakemake
+  - workflow
+  - reproducibility
+  - data Analysis
+license: "MIT"

scripts/common.py

@@ -6,6 +6,7 @@
 import time
 
 from ratelimit import limits, sleep_and_retry
+from jinja2 import Environment, FileSystemLoader, select_autoescape
 from github import Github
 from github.ContentFile import ContentFile
 from github.GithubException import UnknownObjectException, RateLimitExceededException
@@ -15,6 +16,10 @@
 test_repo = os.environ.get("TEST_REPO")
 offset = int(os.environ.get("OFFSET", 0))
 
+env = Environment(
+    autoescape=select_autoescape(["html"]), loader=FileSystemLoader("templates")
+)
+
 # do not clone LFS files
 os.environ["GIT_LFS_SKIP_SMUDGE"] = "1"
 g = Github(os.environ["GITHUB_TOKEN"])

source/_templates/workflow_page.md

@@ -10,6 +10,12 @@
 ![](https://img.shields.io/github/{{ badge }}/{{ wf["full_name"] }}?style=flat&label={{ badge }})
 :::
 {% endfor %}
+:::{grid-item}
+:columns: auto
+:margin: 0
+:padding: 1
+[![](https://img.shields.io/badge/GitHub%20page-blue?style=flat)](https://github.com/{{ wf["full_name"] }})
+:::
 ::::
 
 {{ wf["description"] }}
@@ -29,7 +35,7 @@
     {bdg-danger}`linting: failed`
 {%- endif -%},
 **Formatting:**
-{%- if wf["formatting"] == None -%}
+{% if wf["formatting"] == None -%}
     {bdg-success}`formatting: passed`
 {%- else -%}
     {bdg-danger}`formatting: failed`
@@ -133,12 +139,24 @@ _The following section is imported from the workflow's `config/README.md`_.
 
 ### Linting results
 
+{% if wf["linting"] == None %}
+```
+All tests passed!
+```
+{%- else -%}
 ```
 {{ wf["linting"] }}
 ```
+{% endif %}
 
 ### Formatting results
 
+{% if wf["formatting"] == None %}
+```
+All tests passed!
+```
+{%- else -%}
 ```
 {{ wf["formatting"] }}
 ```
+{% endif %}

source/docs/about/adding_workflows.md

@@ -1,9 +1,9 @@
 
-# Adding workflows
+## Adding workflows
 
 Workflows are **automatically added** to the Workflow Catalog. This is done by regularly searching Github repositories for matching workflow structures. The catalog includes workflows based on the following criteria.
 
-## Generic workflows
+### Generic workflows
 
 - The workflow is contained in a public Github repository.
 - The repository has a `README.md` file, containing the words "snakemake" and "workflow" (case insensitive).
@@ -12,11 +12,11 @@ Workflows are **automatically added** to the Workflow Catalog. This is done by r
 - The repository is small enough to be cloned into a [Github Actions](https://docs.github.com/en/actions/about-github-actions/understanding-github-actions) job (very large files should be handled via [Git LFS](https://docs.github.com/en/repositories/working-with-files/managing-large-files), so that they can be stripped out during cloning).
 - The repository is not blacklisted here.
 
-## *Standardized Usage* workflows
+### *Standardized Usage* workflows
 
 In order to additionally appear in the "standardized usage" area, repositories additionally have to:
 
-- have their main workflow definition named `workflow/Snakefile` (unlike for plain inclusion (see above), which also allows just `Snakefile` in the root of the repository),
+- have their main workflow definition named `workflow/Snakefile` (unlike for [plain inclusion](#generic-workflows), which also allows just `Snakefile` in the root of the repository),
 - provide configuration instructions under `config/README.md`
 - contain a `YAML` file `.snakemake-workflow-catalog.yml` in their root directory, which configures the usage instructions displayed by this workflow catalog.
 
@@ -44,6 +44,6 @@ The content of the `.snakemake-workflow-catalog.yml` file is subject to change.
 
 Once included in the standardized usage area you can link directly to the usage instructions for your repository via the URL `https://snakemake.github.io/snakemake-workflow-catalog?usage=<owner>/<repo>`. Do not forget to replace the `<owner>` and `<repo>` tags at the end of the URL.
 
-## Release handling
+### Release handling
 
 If your workflow provides Github releases, the catalog will always just scrape the latest non-preview release. Hence, in order to update your workflow's records here, you need to release a new version on Github.

source/docs/about/contributions.md

@@ -1,13 +1,13 @@
 
-# Contributions
+## Contributions
 
 Contributions to the Snakemake Workflow Catalog are welcome!
 Ideas can be discussed on the [catalog's Issues page](https://github.com/snakemake/snakemake-workflow-catalog/issues) first, and contributions made through Github Pull Requests.
 
-## License
+### License
 
 The Snakemake Workflow Catalog is open-source and available under the [MIT License](https://choosealicense.com/licenses/mit/).
-For more information and to explore the available workflows, visit https://snakemake.github.io/snakemake-workflow-catalog/.
+For more information about the individual workflows, browse the [list of *standardized usage* workflows](<all_standardized_workflows>).
 
 :::{note}
 All workflows collected and presented on the Catalog are licensed under their own terms!

source/docs/about/purpose.md

@@ -1,5 +1,5 @@
 
-# Purpose
+## Purpose
 
 This repository serves as a centralized collection of workflows designed to facilitate reproducible and scalable data analyses using the [**Snakemake**](https://snakemake.github.io/) workflow management system.
 

source/docs/about/using_workflows.md

@@ -1,7 +1,7 @@
 
-# Using workflows
+## Using workflows
 
-## Basic usage
+### Basic usage
 
 To get started with a workflow from the catalog:
 
@@ -29,15 +29,13 @@ cd <workflow-dir>
 snakemake --cores 2
 ```
 
-:::tip Dry-run
-
+:::{tip}
 Use the `--dry-run` option first to check if all inputs are found.
-
 :::
 
-For more detailed instructions, please refer to the individual documentation for each [workflow](<docs/all_standardized_workflows>).
+For more detailed instructions, please refer to the individual documentation for each [workflow](<all_standardized_workflows>).
 
-## Deployment options
+### Deployment options
 
 The deployment method is controlled using the `--software-deployment-method` (short `--sdm`) argument.
 

source/docs/catalog.md

@@ -3,70 +3,18 @@
 
 ```{toctree}
 :hidden:
-
-about/purpose
-about/using_workflows
-about/adding_workflows
-about/contributions
 ```
 
 Here you can find the most important information about the **Snakemake workflow catalog**.
 
-*Estimated reading time: 5 minutes*.
-
-:::
-## Use a workflow from the catalog
-:::
-
-1. Clone the repository or download the specific workflow directory.
-
-```bash
-git clone https://github.com/<user>/<workflow>
+```{include} about/purpose.md
 ```
 
-2. Review the documentation provided with the workflow to understand its requirements and usage.
-
-3. Configure the workflow by editing the `config.yml` files as needed.
-
-4. Create an environment with access to Snakemake. It is recommended to use `mamba`.
-
-```bash
-mamba create -n <env-name> -c <channels> snakemake
-mamba activate <env-name>
+```{include} about/using_workflows.md
 ```
 
-5. Execute the workflow using Snakemake.
-
-```bash
-cd <workflow-dir>
-snakemake --cores 2
+```{include} about/adding_workflows.md
 ```
 
-:::tip Dry-run
-
-Use the `--dry-run` option first to check if all inputs are found.
-
-:::
-
-For more detailed instructions, please refer to the individual documentation for each [workflow](workflows/top_wf_by_stars.mdx).
-
-:::
-## Add a workflow to the catalog
-:::
-
-Workflows are **automatically added** to the Workflow Catalog. This is done by regularly searching Github repositories for matching workflow structures. The catalog includes workflows based on the following criteria.
-
-The catalog currently discriminates between two types of workflows based on their documentation:
-
-**Generic workflows**
-
-- all snakemake workflows in public Github repositories
-- repositories need to have a `README.md` file containing the words "snakemake" and "workflow"
-- also need to have a workflow definition named either `Snakefile` or `workflow/Snakefile`, and contain rules in `*.smk` format.
-
-**Standardized Usage workflows**
-
-- workflows that additionally adhere to standards of the workflow catalog
-- main workflow definition must be named `workflow/Snakefile`
-- provide configuration instructions under `config/README.md`
-- contain a `.snakemake-workflow-catalog.yml` file with instructions on deployment options
+```{include} about/contributions.md
+```

source/docs/snakemake.md

@@ -5,31 +5,15 @@
 :hidden:
 ```
 
-## What is 'snakemake'?
+## What is Snakemake?
 
-The Snakemake workflow management system is a tool to create reproducible and scalable data analyses. Workflows are described via a human readable, Python based language. They can be seamlessly scaled to server, cluster, grid and cloud environments, without the need to modify the workflow definition. Finally, Snakemake workflows can entail a description of required software, which will be automatically deployed to any execution environment.
+The Snakemake workflow management system is a tool to create reproducible and scalable data analyses. Workflows are described *via* a human readable, Python based language. They can be seamlessly scaled to server, cluster, grid and cloud environments, without the need to modify the workflow definition.
 
-## Basic usage
+- To learn more about Snakemake, visit the [Snakemake homepage!](https://snakemake.github.io/)
 
-Snakemake usage is [extensively documented here](https://snakemake.readthedocs.io/en/stable/).
+- To get an impression of the Snakemake architecture, [read the Snakemake paper](https://doi.org/10.12688/f1000research.29032.2)
 
-Snakemake is organized in `rules`, which define specific input and output files. 
-Files are processed using code which is for example directly deployed with the `shell` directive, or with external `python` and `R` scripts, or even directly rendered `markdown` based notebooks.
-
-To get a first impression:
-
-```bash
-rule select_by_country:
-    input:
-        "data/worldcitiespop.csv"
-    output:
-        "by-country/{country}.csv"
-    shell:
-        "xsv search -s Country '{wildcards.country}' "
-        "{input} > {output}"
-```
-
-In this code chunk, the input table `data/worldcitiespop.csv` is searched by the keyword `country`, which is used as a wildcard to construct new file names for the output. The result is that all lines from the original table are split by Country and saved as separare files in a new output directory.
+- To learn how to use Snakemake workflows, [read the documentation](https://snakemake.readthedocs.io/en/stable/).
 
 ## Create your own workflows