Merge pull request #172 from nextflow-io/docs/faq-page

nvnieuwk · web-flow · commit c0caaa5c4392 · 2025-08-22T16:06:23.000+02:00
Add troubleshooting and FAQ pages
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 1. Added a new configuration option: `validation.help.enumLength` which sets the maximum length of enum values in the help message. The default is set to the value in the `COLUMNS` environment variable or 100 character if that variable isn't set.
 2. Added top-level schema description for detailed help `--help <args>`. If `<args>` is associated with a schema, then the top-level fields will be shown similarly to `--help` for the main schema (#146).
+3. Added a Troubleshooting and FAQ page to the documentation.
 
 ## Changes
 
diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md
@@ -66,7 +66,7 @@ To preview the docs, open the URL provided by mkdocs in your browser.
    - `github_username`: The GitHub username granting access to the plugin repository.
    - `github_access_token`: The GitHub access token required to upload and commit changes to the plugin repository.
    - `github_commit_email`: The email address associated with your GitHub account.
-3. Update the [changelog](./CHANGELOG.md).
+3. Update the [changelog](https://github.com/nextflow-io/nf-schema/blob/master/CHANGELOG.md).
 4. Build and publish the plugin to your GitHub repository:
    ```bash
    make release
diff --git a/docs/extras/faq.md b/docs/extras/faq.md
@@ -0,0 +1,21 @@
+# Frequently Asked Questions
+
+## What pipelines are great examples of nf-schema usage?
+
+Here's a list of pipelines that are considered great examples of nf-schema usage:
+
+1. [nf-core pipelines](https://nf-co.re/pipelines/)
+2. [Joon-Klaps/viralgenie](https://github.com/Joon-Klaps/viralgenie)
+3. [genomic-medicine-sweden/nallo](https://github.com/genomic-medicine-sweden/nallo)
+4. [nf-cmgg/smallvariants](https://github.com/nf-cmgg/smallvariants)
+5. And many more...
+
+Feel free to open a pull request to add more examples!
+
+## How can I contribute to nf-schema?
+
+Take a look at the [contribution instruction](../contributing/setup.md) to get started with contributing to nf-schema.
+
+## Where can I ask other questions?
+
+If you have a question that is not addressed in this FAQ, feel free to create an issue on the nf-schema repository [here](https://github.com/nextflow-io/nf-schema/issues) or ask your question in the `#nf-schema` Slack channel on the [Nextflow Slack](https://www.nextflow.io/slack-invite.html) or the [nf-core Slack](https://nf-co.re/join/slack)
diff --git a/docs/extras/troubleshooting.md b/docs/extras/troubleshooting.md
@@ -0,0 +1,23 @@
+# Troubleshooting
+
+This section of the documentation contains a couple of common errors encountered while implementing nf-schema or using pipelines with the plugin and how to solve them.
+
+## An integer value is failing because a string value was expected
+
+Pipelines often use some kind of identifier field in their sample sheet, that usually gets `string` as the expected input. This can cause some issues when using CSV and TSV sample sheets since the types of all values are automatically inferred for these file types. Meaning that a value in the `sample` field that has `123` as the value would result in an integer instead of a string. Following error would be shown in this case:
+
+```
+-> Entry 1: Error for field 'sample' (123): Value is [integer] but should be [string]
+```
+
+There are multiple ways to solve this issue as pipeline developers and as pipeline users. The solutions will be listed from best options to worst:
+
+### Pipeline user
+
+- Option 1: Use a YAML or JSON file as sample sheet if that is allowed by the pipeline and make sure to quote the value. (`'123'` in the case of the example above)
+- Option 2: Activate [lenient validation mode](../configuration/configuration.md#lenientmode). Keep in mind that this will enable lenient validation for **ALL** validations in the pipeline.
+
+### Pipeline developer
+
+- Option 1: Modify `"type": "string"` in the affected JSON schema to `"type": ["string", "integer"]`. Make sure that integer values don't break anything in your pipeline. The easiest way to ensure compatibility is to cast the value to a string after converting the sample sheet to a list.
+- Option 2: Enforce usage of JSON and YAML sample sheets by only allowing files ending in `.yml`, `.yaml` or `.json` to be used.
diff --git a/docs/index.md b/docs/index.md
@@ -15,8 +15,8 @@ description: Nextflow plugin for sample sheet validation
 
     nf-schema is the new version of the now deprecated [nf-validation](https://github.com/nextflow-io/nf-validation). Please follow the [migration guide](https://nextflow-io.github.io/nf-schema/latest/migration_guide/) to migrate your code to this new version.
 
-[Parameter schema specs](nextflow_schema/nextflow_schema_specification/){ .md-button .md-button--primary }
-[Sample sheet schema specs](nextflow_schema/sample_sheet_schema_specification/){ .md-button }
+[Parameter schema specs](nextflow_schema/nextflow_schema_specification.md){ .md-button .md-button--primary }
+[Sample sheet schema specs](nextflow_schema/sample_sheet_schema_specification.md){ .md-button }
 
 ## Introduction
 
diff --git a/docs/migration_guide.md b/docs/migration_guide.md
@@ -36,7 +36,7 @@ Updating your pipeline can be done in a couple simple steps.
 
 ### Updating the name and version of the plugin
 
-The name and the version of the plugin should be updated from `nf-validation` to `nf-schema@2.0.0`:
+The name and the version of the plugin should be updated from `nf-validation` to any version of `nf-schema@2.x.x`:
 
 === "nf-validation"
 
@@ -50,7 +50,7 @@ The name and the version of the plugin should be updated from `nf-validation` to
 
     ```groovy
     plugins {
-        id 'nf-schema@2.0.0'
+        id 'nf-schema@2.x.x'
     }
     ```
 
diff --git a/docs/nextflow_schema/nextflow_schema_examples.md b/docs/nextflow_schema/nextflow_schema_examples.md
@@ -13,10 +13,10 @@ It is used as a test fixture in the nf-schema package [here](https://github.com/
 
 !!! note
 
-    More examples can be found in the plugin [`testResources` directory](https://github.com/nextflow-io/nf-schema/master/plugins/nf-schema/testResources/).
+    More examples can be found in the plugin [`testResources` directory](https://github.com/nextflow-io/nf-schema/tree/master/src/testResources).
 
 ```json
 --8<-- "src/testResources/nextflow_schema.json"
 ```
 
-Even more examples can be found in the plugin [`examples` directory](../../examples) in the GitHub repository.
+Even more examples can be found in the plugin [`examples` directory](https://github.com/nextflow-io/nf-schema/tree/master/examples) in the GitHub repository.
diff --git a/docs/nextflow_schema/sample_sheet_schema_examples.md b/docs/nextflow_schema/sample_sheet_schema_examples.md
@@ -63,4 +63,4 @@ It is used as a test fixture in the nf-schema package [here](https://github.com/
 --8<-- "src/testResources/schema_input.json"
 ```
 
-Even more examples can be found in the plugin [`examples` directory](../../examples) in the GitHub repository.
+Even more examples can be found in the plugin [`examples` directory](https://github.com/nextflow-io/nf-schema/tree/master/examples) in the GitHub repository.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -13,7 +13,7 @@ nav:
       - nextflow_schema/sample_sheet_schema_examples.md
   - Tutorials:
       - nextflow_schema/create_schema.md
-      - migration_guide.md
+      - Nf-validation migration guide: migration_guide.md
   - Reference:
       - nextflow_schema/nextflow_schema_specification.md
       - nextflow_schema/sample_sheet_schema_specification.md
@@ -25,6 +25,9 @@ nav:
       - Samplesheet parsing: samplesheets/samplesheetToList.md
       - Samplesheet examples: samplesheets/examples.md
       - Other validation: validate/validate.md
+  - Extras:
+      - FAQ: extras/faq.md
+      - extras/troubleshooting.md
   - Contributing:
       - contributing/setup.md
 
