Skip to content

Add new component: quarto/partial#12187

Open
fasterius wants to merge 2 commits into
nf-core:masterfrom
fasterius:quarto/partial
Open

Add new component: quarto/partial#12187
fasterius wants to merge 2 commits into
nf-core:masterfrom
fasterius:quarto/partial

Conversation

@fasterius

Copy link
Copy Markdown
Contributor

This PR adds a new module: quarto/partial, which aims to add new functionality for Quarto within nf-core. The quartonotebook already exists, which can render Quarto/Jupyter/RMarkdown reports into HTML, but it only creates a single, monolithic report and can't be extended. Quarto has various ways of working with sub-reports or extending reports, which is what this new module is all about. The major use case is allowing for more granular reporting flow, dividing work up in arbitrary steps to reduce re-computation (e.g. when iterating over some analysis step or re-running a pipeline with a different set of parameters for only some of the reporting steps) while still allowing for a single output report.

There are two major ways of working with sub-reports or extended reports in Quarto: Quarto Projects, and Quarto Partials. Projects do not play well within a workflow manager context, as Quarto then needs to be the arbiter of what gets executed at what time, which depends on the working directory state (which will always be fresh in a Nextflow context). Partials, however, fits more nicely into the workflow manager context: a sub-report is first rendered to markdown (not HTML), which is then referred to in the final report using the {{< include partial.md >}} notation, and the final report is rendered only once.

While the quartonotebook module is already quite flexible, there are several reasons why incorporating partial rendering into it doesn't work well:

  • Separation of concerns: the quartonotebook module renders a single Quarto document to HTML, where partials needs to render intermediate markdown documents.
  • While some input/output is shared, there is some non-overlapping parts: partials do not use extensions, while the main output differs (an HTML versus a markdown + related files, e.g. images). Having a single module would mean that almost all output would be optional due to having to account for the different render modes, which feels brittle to me.
  • Rendering a partial needs to explicitly use --to markdown, which overwrites whatever has been specified in the report. The quartonotebook module doesn't use --to at all, which allows a user to specify the format in the .qmd file themselves, which might include a custom format in e.g. an extension. Keeping the modules separate here makes it easier to work with both, circumventing having to use ext.args for every single module use (which would also be more opaque).
  • Partials are more of a pure Quarto thing, and while it's probably possible to make it work with the other input types that quartonotebook can handle, I had some issues there. If somebody is working with partials, it is reasonable to assume a Quarto-centric system, thus removing support of the other formats (.ipynb and .rmd) and for the test suite.

A lot of the script: part of the modules remain similar, though, but I believe it's worth it due to the above mentioned things.

Should this module be accepted, the existing quartonotebook module would need to be renamed to e.g. quarto/notebook. I'm not sure what the procedure for renaming modules is, but I'm happy to make a PR both to the modules repository for this, as well as for all of the pipelines currently using the module (which is four, at time of writing) after its been updated.

PR checklist

  • This comment contains a description of changes (with reason).
  • If you've fixed a bug or added code that should be tested, add tests!
  • If you've added a new tool - have you followed the module conventions in the contribution docs
  • Remove all TODO statements.
  • Broadcast software version numbers to topic: versions - See version_topics
  • Follow the naming conventions.
  • Follow the parameters requirements.
  • Follow the input/output options guidelines.
  • Add a resource label
  • Use BioConda and BioContainers if possible to fulfil software requirements.
  • Ensure that the test works with either Docker / Singularity. Conda CI tests can be quite flaky:
    • For modules:
      • nf-core modules test <MODULE> --profile docker
      • nf-core modules test <MODULE> --profile singularity
      • nf-core modules test <MODULE> --profile conda

@fasterius
fasterius requested a review from mahesh-panchal June 29, 2026 08:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants