Add more complete docs

[FerriolCalvet]

The basics would be something similar to what is available for the nf-core pipelines, with the most mandatory summary would be an explanation of the usage, and an explanation on the outputs.

• Usage
  • Different pipeline modes
  • Different parameters for each run
• Outputs
• Explain different file formats required for the inputs
• Explanation of internal logic and methods

[FerriolCalvet]

we are missing a bit more of explanation on how to download Ensembl VEP (i.e. 111 version that is the one we are using everywhere)

[FerriolCalvet]

we are missing a bit more of explanation on how to download Ensembl VEP (i.e. 111 version that is the one we are using everywhere)

@migrau can you add this? whenever you have time, I am continuing with the rest of things

[migrau]

I don't think we need to repeat the instructions from the official VEP documentation; it is already quite good. I edited the link to point directly to the VEP cache section and specified a bit the params to change.

On the other hand, and totally off-topic, is it worth testing the last VEP version, v114?

[FerriolCalvet]

I think that for a first round of complete documentation the current status of this branch is complete enough.

More detailed explanation on the outputs and the methods will be available initially in the supplementary material of the normal bladder paper and then more extensively explained in a standalone article.

We can discuss if we want to keep the basic Nextflow parameters explanation in the usage document.
I would personally keep it there at the bottom of the file just in case people find it useful.

[Copilot]

Pull Request Overview

This PR enriches and expands the project documentation and adjusts the pipeline configuration to support new parameters and clean up deprecated blocks.

• Reorganized nextflow.config, adding new profiling flags, reordering parameters, and removing unused validation settings
• Removed the standalone Ensembl VEP download module (meta.yml and main.nf) and its related config
• Added and fleshed out detailed documentation in docs/ (usage, outputs, file formatting) and updated root README

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
nextflow.config	Reordered params, added new profiling flags, removed validation.
modules/nf-core/ensemblvep/download/meta.yml	Removed obsolete module metadata file.
modules/nf-core/ensemblvep/download/main.nf	Removed obsolete download process definition.
docs/usage.md	Expanded usage guide with command examples and run modes.
docs/output.md	Detailed pipeline output directory structure and step descriptions.
docs/file_formatting.md	New document describing required and optional input file formats.
docs/README.md	Updated documentation TOC and overview descriptions.
conf/modules.config	Removed deprecated ENSEMBLVEP_DOWNLOAD process settings.
assets/useful_scripts/deepcsa_maf2samplevcfs.py	Cleaned up comment blocks around usage instructions.
README.md	Refined project introduction, usage instructions, and warnings.
.markdownlint.json	Added custom markdownlint rules.

Comments suppressed due to low confidence (5)

docs/file_formatting.md:32

• The parameter use_custom_bedfile is documented here but does not exist in nextflow.config; reconcile the docs or add the missing config parameter.

    use_custom_bedfile          = false

docs/usage.md:157

• The regressions parameter is referenced but isn't defined in nextflow.config; add the parameter or update the docs accordingly.

    regressions                 = true

docs/README.md:6

• [nitpick] Nested list indentation contains an extra hyphen; use a single - for sub-items to improve readability.

  - An overview of how the pipeline works and how to run it.

[Copilot]

Changing the DAG output extension to .mmd may break downstream viewers or expectations; consider using a more widely supported format (e.g., .html or .svg) or documenting this change.

Suggested change

	file = "${params.outdir}/pipeline_info/pipeline_dag_${new java.util.Date().format( 'yyyy-MM-dd_HH-mm-ss')}.mmd"
	file = "${params.outdir}/pipeline_info/pipeline_dag_${new java.util.Date().format( 'yyyy-MM-dd_HH-mm-ss')}.svg"

[migrau]

I would point to the nf-core documentation instead adding this info here: https://nf-co.re/docs/usage/getting_started/configuration#basic-configuration-profiles

[FerriolCalvet]

I am only worried that there might be some definitions there that are not exactly the same as here, but it is also true that I did not curate well the description of the profiles below...

if you want to give it a try and remove all this last part on "Additional Nextflow documentation" I am happy to look at it. If this means removing it all I guess it should be fine, we can maybe do this and if then whenever someone starts using this (if anyone does) if there is some feedback on what does not work we can add some more information, do you agree?

If you do, we remove all these last section and add the link you mentioned here.

[migrau]

link is to rnaseq instead deepCSA

[FerriolCalvet]

we are likely removeing this part

[migrau]

these are the things that you need to prepare for the initial RUN right? it includes some params, i.e.:

params {
    plot_depths   = true
    signatures    = true
    profileall    = true
}

but also some inputs, e.g. "Definition of regions to analyze"? It is not clear to me.
I think I would separate it. For the params part, you can include a comment within the code example:

# Enables plotting depth per sample and/or per gene, mutational profile/signatures, 
# and needle plots for somatic mutations
params {
    plot_depths   = true
    signatures    = true
    profileall    = true
}

[FerriolCalvet]

the list of definition of regions to analyze and all these things are the "analysis" provided if you run the pipeline with these params described below. it is kind of a summary of the outputs/goals that you can achieve with this run mode