docs: Add developing modules tutorial#4155
Open
christopher-hakkaart wants to merge 4 commits intomainfrom
Open
docs: Add developing modules tutorial#4155christopher-hakkaart wants to merge 4 commits intomainfrom
christopher-hakkaart wants to merge 4 commits intomainfrom
Conversation
✅ Deploy Preview for nf-core-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for nf-core-main-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Member
Author
|
@nf-core-bot fix linting |
jfy133
reviewed
Apr 20, 2026
Member
jfy133
left a comment
jfy133
left a comment
There was a problem hiding this comment.
Got side tracked and have to get kits up now, but conceptual question on first page for consideration
|
|
||
| Duration: **4hr** | ||
|
|
||
| Original author: James A. Fellows Yates (@jfy133), with corrections and improvements from Niklas Schandry (@nschan) and Alexandru Mizeranschi (@amizeranschi). |
Member
There was a problem hiding this comment.
Suggested change
| Original author: James A. Fellows Yates (@jfy133), with corrections and improvements from Niklas Schandry (@nschan) and Alexandru Mizeranschi (@amizeranschi). | |
| Original author: James A. Fellows Yates (@jfy133), with corrections and improvements from Niklas Schandry (@nschan) and Alexandru Mizeranschi (@amizeranschi). | |
| Refreshed style by: Chris Hakkaart (@christopher-hakkaart ) |
| @@ -0,0 +1,57 @@ | |||
| --- | |||
Member
There was a problem hiding this comment.
One thing I was never sure about in the first version was whether it made sense having this page actually as an index.md or overview.md page instead of the first chapter... what do you think?
Member
Author
There was a problem hiding this comment.
Yeah, I wasn't convinced by this either, but decided it really doesn't matter in the scheme of things.
I think Overview is more of a summary, but this is more of a setting-the-scene, which is more of an Introduction.
IMO - it's fine the way it is. If we have more tutorials and something else fits better, we can reshuffle them.
Member
Author
|
Also - feel free to push changes. I'm not attached to anything strongly. |
jfy133
reviewed
Apr 20, 2026
Member
jfy133
left a comment
jfy133
left a comment
There was a problem hiding this comment.
Finished up to page 3, will continue from 4 onwards when I have time
| Original author: James A. Fellows Yates (@jfy133), with corrections and improvements from Niklas Schandry (@nschan) and Alexandru Mizeranschi (@amizeranschi). | ||
| ::: | ||
|
|
||
| An nf-core module is an atomic, standardised, reproducible, and tested [Nextflow DSL2 module](https://www.nextflow.io/docs/latest/module.html). You can install an nf-core module into any Nextflow pipeline with a single command, then integrate it into your workflow thanks to its consistent internal structure. |
Member
There was a problem hiding this comment.
Suggested change
| An nf-core module is an atomic, standardised, reproducible, and tested [Nextflow DSL2 module](https://www.nextflow.io/docs/latest/module.html). You can install an nf-core module into any Nextflow pipeline with a single command, then integrate it into your workflow thanks to its consistent internal structure. | |
| An nf-core module is an atomic, standardised, reproducible, and tested [Nextflow DSL2 module](https://www.nextflow.io/docs/latest/module.html). | |
| You can install an nf-core module into any Nextflow pipeline with a single command, then efficiently integrate it into your workflow thanks to its consistent internal structure. |
| shortTitle: "Chapter 3: What is a module?" | ||
| --- | ||
|
|
||
| An nf-core module is an opinionated, open-source Nextflow wrapper around a single command-line tool or script. The [central community repository](https://github.com/nf-core/modules) holds more than [1000 modules](https://nf-co.re/modules) that you can reuse in your own pipelines. |
Member
There was a problem hiding this comment.
Suggested change
| An nf-core module is an opinionated, open-source Nextflow wrapper around a single command-line tool or script. The [central community repository](https://github.com/nf-core/modules) holds more than [1000 modules](https://nf-co.re/modules) that you can reuse in your own pipelines. | |
| An nf-core module is an opinionated, open-source Nextflow wrapper around a single command-line tool or script. The [central community repository](https://github.com/nf-core/modules) holds more than [1800 modules](https://nf-co.re/modules) that you can reuse in your own pipelines. |
| :::info{collapse title="Comparison with Nextflow modules"} | ||
| A Nextflow process or module has no restrictions on the number of tools or subcommands it can execute. | ||
|
|
||
| An nf-core module aims for a single analysis command per module. This atomic design supports lego-block construction of pipelines and makes modules easier to understand, share, and test, although it is not always the most resource-efficient approach. |
Member
There was a problem hiding this comment.
Suggested change
| An nf-core module aims for a single analysis command per module. This atomic design supports lego-block construction of pipelines and makes modules easier to understand, share, and test, although it is not always the most resource-efficient approach. | |
| An nf-core module aims for a single analysis command per module. | |
| This atomic design supports lego-block construction of pipelines and makes modules easier to understand, share, and test, although it is not always the most resource-efficient approach. |
| - Use of [meta maps](../../../specifications/components/modules/general#use-of-meta-maps). | ||
| - Use of [stubs](../../../specifications/components/modules/general#stubs). | ||
|
|
||
| The specifications also expand the minimum file set from a single Nextflow `.nf` script to five required files. This reflects the nf-core focus on standardisation, reproducibility, and high-quality documentation. |
Member
There was a problem hiding this comment.
Suggested change
| The specifications also expand the minimum file set from a single Nextflow `.nf` script to five required files. This reflects the nf-core focus on standardisation, reproducibility, and high-quality documentation. | |
| The specifications also expand the minimum required single file from a single Nextflow `.nf` script to five required files. | |
| This reflects the nf-core focus on standardisation, reproducibility, and high-quality documentation. |
|
|
||
| The following diagram shows how these files relate to each other: | ||
|
|
||
| <img width=80% alt="Diagram showing how the execution, documentation, and testing files in an nf-core module relate to each other." src="../../../../../assets/images/tutorials/training/nf-core-module-file-relationship.png"> |
jfy133
reviewed
Apr 21, 2026
Member
jfy133
left a comment
jfy133
left a comment
There was a problem hiding this comment.
Chapter 5 review done. Continuing next time from chapter 6
| ```bash | ||
| nf-core modules create <toolname>/<subcommand> | ||
| ``` | ||
|
|
Member
There was a problem hiding this comment.
Suggested change
| :::note | |
| If your module does not have subcommands, just use `<toolname>` | |
| ::: | |
| ### Naming conventions | ||
|
|
||
| - All parts of the module name must be lowercase, alphanumeric, with no punctuation or special characters. | ||
| - Single-command tools use the tool name only. For a tool executed with `fastp -i <input> -o <output>`, run `nf-core modules create fastp`. |
Member
There was a problem hiding this comment.
Suggested change
| - Single-command tools use the tool name only. For a tool executed with `fastp -i <input> -o <output>`, run `nf-core modules create fastp`. | |
| - Single-command tools use the tool name only. For example, for a tool executed with `fastp -i <input> -o <output>`, run `nf-core modules create fastp`. |
|
|
||
| - All parts of the module name must be lowercase, alphanumeric, with no punctuation or special characters. | ||
| - Single-command tools use the tool name only. For a tool executed with `fastp -i <input> -o <output>`, run `nf-core modules create fastp`. | ||
| - Tools with subcommands use `<tool>/<subcommand>`, even if you only plan to wrap one subcommand. For `samtools view`, run `nf-core modules create samtools/view`. |
Member
There was a problem hiding this comment.
Suggested change
| - Tools with subcommands use `<tool>/<subcommand>`, even if you only plan to wrap one subcommand. For `samtools view`, run `nf-core modules create samtools/view`. | |
| - Tools with subcommands use `<tool>/<subcommand>`, even if you only plan to wrap one subcommand. For example, `samtools view`, run `nf-core modules create samtools/view`. |
|
|
||
| ### Prompts from `nf-core modules create` | ||
|
|
||
| The command tries to pre-fill the boilerplate. It searches [Bioconda](https://bioconda.github.io/) and [biocontainers](https://biocontainers.pro/) for the latest version of your tool and adds the container definitions automatically. |
Member
There was a problem hiding this comment.
Suggested change
| The command tries to pre-fill the boilerplate. It searches [Bioconda](https://bioconda.github.io/) and [biocontainers](https://biocontainers.pro/) for the latest version of your tool and adds the container definitions automatically. | |
| The command tries to pre-fill the boilerplate. | |
| It searches [Bioconda](https://bioconda.github.io/) and [biocontainers](https://biocontainers.pro/) for the latest version of your tool and adds the container definitions automatically. |
| shortTitle: "Chapter 5: Writing modules" | ||
| --- | ||
|
|
||
| Once you have generated the boilerplate template files, you can update them to make your module function. The boilerplate contains many `TODO` comments and example content to guide you. |
Member
There was a problem hiding this comment.
Suggested change
| Once you have generated the boilerplate template files, you can update them to make your module function. The boilerplate contains many `TODO` comments and example content to guide you. | |
| Once you have generated the boilerplate template files, you can update them to make your module function. | |
| The boilerplate contains many `TODO` comments and example content to guide you. |
Comment on lines
+448
to
+452
|
|
||
| cat <<-END_VERSIONS > versions.yml | ||
| "${task.process}": | ||
| tool: \$(samtools --version |& sed '1!d ; s/samtools //') | ||
| END_VERSIONS |
Member
There was a problem hiding this comment.
Suggested change
| cat <<-END_VERSIONS > versions.yml | |
| "${task.process}": | |
| tool: \$(samtools --version |& sed '1!d ; s/samtools //') | |
| END_VERSIONS |
| """ | ||
| ``` | ||
|
|
||
| Keep the `versions.yml` HEREDOC command. It runs during the dry run. |
Member
There was a problem hiding this comment.
Suggested change
| Keep the `versions.yml` HEREDOC command. It runs during the dry run. |
|
|
||
| ## The `meta.yml` file | ||
|
|
||
| The `meta.yml` file documents the module with descriptions, keywords, and links to the tool's resources. This information powers the searchable [modules page](https://nf-co.re/modules), improves discoverability on external databases, and supports future automated linkage between modules. |
Member
There was a problem hiding this comment.
Suggested change
| The `meta.yml` file documents the module with descriptions, keywords, and links to the tool's resources. This information powers the searchable [modules page](https://nf-co.re/modules), improves discoverability on external databases, and supports future automated linkage between modules. | |
| The `meta.yml` file documents the module with descriptions, keywords, and links to the tool's resources. | |
| This information powers the searchable [modules page](https://nf-co.re/modules), improves discoverability on external databases, and supports future automated linkage between modules. |
Comment on lines
+523
to
+527
| - versions: | ||
| - "versions.yml": | ||
| type: file | ||
| description: File containing software versions | ||
| pattern: "versions.yml" |
Member
There was a problem hiding this comment.
Suggested change
| - versions: | |
| - "versions.yml": | |
| type: file | |
| description: File containing software versions | |
| pattern: "versions.yml" | |
| versions_drep: | |
| - - ${task.process}: | |
| type: string | |
| description: The name of the process | |
| - drep: | |
| type: string | |
| description: The name of the tool | |
| - drep version 2>&1 | sed 's/^.*drep v//': | |
| type: eval | |
| description: The expression to obtain the version of the tool | |
| topics: | |
| versions: | |
| - - ${task.process}: | |
| type: string | |
| description: The name of the process | |
| - drep: | |
| type: string | |
| description: The name of the tool | |
| - drep version 2>&1 | sed 's/^.*drep v//': | |
| type: eval | |
| description: The expression to obtain the version of the tool |
Comment on lines
+729
to
+733
| - versions: | ||
| - versions.yml: | ||
| type: file | ||
| description: File containing software versions | ||
| pattern: "versions.yml" |
Member
There was a problem hiding this comment.
Suggested change
| - versions: | |
| - versions.yml: | |
| type: file | |
| description: File containing software versions | |
| pattern: "versions.yml" | |
| versions_bwamem2: | |
| - - ${task.process}: | |
| type: string | |
| description: The name of the process | |
| - bwamem2: | |
| type: string | |
| description: The name of the tool | |
| - bwa-mem2 version | grep -o -E "[0-9]+(\.[0-9]+)+": | |
| type: eval | |
| description: The expression to obtain the version of the tool | |
| versions_samtools: | |
| - - ${task.process}: | |
| type: string | |
| description: The name of the process | |
| - samtools: | |
| type: string | |
| description: The name of the tool | |
| - samtools version | sed '1!d;s/.* //': | |
| type: eval | |
| description: The expression to obtain the version of the tool | |
| topics: | |
| versions: | |
| - - ${task.process}: | |
| type: string | |
| description: The name of the process | |
| - bwamem2: | |
| type: string | |
| description: The name of the tool | |
| - bwa-mem2 version | grep -o -E "[0-9]+(\.[0-9]+)+": | |
| type: eval | |
| description: The expression to obtain the version of the tool | |
| - - ${task.process}: | |
| type: string | |
| description: The name of the process | |
| - samtools: | |
| type: string | |
| description: The name of the tool | |
| - samtools version | sed '1!d;s/.* //': | |
| type: eval | |
| description: The expression to obtain the version of the tool |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4145
@netlify /docs/developing/tutorials/writing-nf-core-modules/1-introduction