Merge pull request #103 from Joon-Klaps/61-update-docs-make-release

61 update docs make release

Author: Joon-Klaps

.devcontainer/devcontainer.json

@@ -33,5 +33,5 @@
         }
     },
 
-    "postCreateCommand": "pre-commit install --install-hooks && nextflow self-update"
+    "postCreateCommand": "pre-commit install --install-hooks && nextflow self-update && pip install mkdocs-material"
 }

.github/workflows/build-docs.yml

@@ -0,0 +1,44 @@
+name: Publish Docs On Change
+on:
+  push:
+    branches:
+      - main
+      - dev
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
+    defaults:
+      run:
+        shell: bash -x -l {0}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # fetch all commits/branches
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: apt-get install pngquant
+      - name: Install dependencies
+        run: pip install mkdocs-material pymdown-extensions pillow cairosvg mike
+      - name: Build docs
+        run: mike deploy --push --update-aliases ${{ env.plugin_version }} latest
+      - name: Set default docs
+        run: mike set-default --push latest

.gitpod.yml

@@ -7,6 +7,9 @@ tasks:
   - name: unset JAVA_TOOL_OPTIONS
     command: |
       unset JAVA_TOOL_OPTIONS
+  - name: Setup mkdocs-material
+    command: |
+      pip install mkdocs-material
 
 vscode:
   extensions: # based on nf-core.nf-core-extensionpack

.nf-core.yml

@@ -6,7 +6,6 @@ lint:
     - docs/README.md
     - .github/ISSUE_TEMPLATE/bug_report.yml
     - .github/ISSUE_TEMPLATE/config.yml
-    - .github/CONTRIBUTING.md
     - .github/ISSUE_TEMPLATE/feature_request.yml
     - .github/PULL_REQUEST_TEMPLATE.md
     - .github/workflows/branch.yml
@@ -27,6 +26,8 @@ lint:
     - report_section_order
     - report_comment
   files_exist:
+    - .github/CONTRIBUTING.md
+    - CITATIONS.md
     - conf/test.config
     - conf/test_full.config
     - lib/Utils.groovy

.prettierignore

@@ -10,3 +10,4 @@ testing/
 testing*
 *.pyc
 bin/
+*.md

README.md

@@ -23,7 +23,7 @@
 
 ## Pipeline summary
 
-![viral-genie-workflow](docs/images/workflow.png)
+![viral-genie-workflow](images/metromap_style_pipeline_workflow_viralgenie.png)
 
 Tools given for each step can change as benchmarking is in progress.
 
@@ -36,58 +36,66 @@ Tools given for each step can change as benchmarking is in progress.
     - Performs taxonomic classification and/or profiling using one or more of:
         - [`Kraken2`](https://ccb.jhu.edu/software/kraken2/)
         - [`Kaiju`](https://kaiju.binf.ku.dk/)
-    - Perform optional post-processing ([`bracken`](https://ccb.jhu.edu/software/bracken/))
-    - Plotting Kraken2, Centrifuge, Kaiju and MALT results ([`Krona`](https://hpc.nih.gov/apps/kronatools.html))
+    - Plotting Kraken2 and Kaiju ([`Krona`](https://hpc.nih.gov/apps/kronatools.html))
 4. Denovo assembly ([`SPAdes`](http://cab.spbu.ru/software/spades/), [`TRINITY`](https://github.com/trinityrnaseq/trinityrnaseq), [`megahit`](https://github.com/voutcn/megahit)), combine contigs.
-5. Contig cluster annotation & binning ([`blastn`](https://blast.ncbi.nlm.nih.gov/Blast.cgi?PAGE_TYPE=BlastSearch))
-
--   Identify top 5 blast hits
--   Merge blast hit seqs and contigs into a single file & cluster ([`cdhit`](https://sites.google.com/view/cd-hit), [`vsearch`](https://github.com/torognes/vsearch/wiki/Clustering))
--   Filter for only contigs that correspond to the identified centroid
-
-6. Scaffolding of contigs ([`MAFFT`](https://mafft.cbrc.jp/alignment/server/), [`MUSCLE`](https://www.drive5.com/muscle/))
-7. Creation of hybrid supercontig by combining contigs and the reference.
-8. Mapping filtered reads to hybrid supercontig ([`BowTie2`](http://bowtie-bio.sourceforge.net/bowtie2/),[`BWAmem2`](https://github.com/bwa-mem2/bwa-mem2))
-9. Update consensus genome with mapped reads ([`BCFTools`](http://samtools.github.io/bcftools/bcftools.html),[`iVar`](https://andersen-lab.github.io/ivar/html/manualpage.html))
-10. Repeat step 8-9 multiple times
-11. Variant calling and annotation ([`BCFTools`](http://samtools.github.io/bcftools/bcftools.html),[`iVar`](https://andersen-lab.github.io/ivar/html/manualpage.html))
-12. Assembly & contig evaluation ([`QUAST`](http://quast.sourceforge.net/quast),[`CheckV`](https://bitbucket.org/berkeleylab/checkv/src/master/),[`blastn`](https://blast.ncbi.nlm.nih.gov/Blast.cgi))
-13. Present QC and visualisation for raw read, alignment, assembly and variant calling results ([`MultiQC`](http://multiqc.info/))
+5. Contig reference idententification ([`blastn`](https://blast.ncbi.nlm.nih.gov/Blast.cgi?PAGE_TYPE=BlastSearch))
+    -   Identify top 5 blast hits
+    -   Merge blast hit and all contigs of a sample
+6. [Optional] Precluster contigs based on taxonomy
+    - Identify taxonomy [`Kraken2`](https://ccb.jhu.edu/software/kraken2/) and [`Kaiju`](https://kaiju.binf.ku.dk/)
+    - Resolve potential incosistencies in taxonomy [`Kaiju-mergeOutputs`](https://kaiju.binf.ku.dk/)
+7. Cluster contigs (or every taxonomic bin) of samples, options are:
+    - [`cdhitest`](https://sites.google.com/view/cd-hit)
+    - [`vsearch`](https://github.com/torognes/vsearch/wiki/Clustering)
+    - [`mmseqs-linclust`](https://github.com/soedinglab/MMseqs2/wiki#linear-time-clustering-using-mmseqs-linclust)
+    - [`mmseqs-cluster`](https://github.com/soedinglab/MMseqs2/wiki#cascaded-clustering)
+    - [`vRhyme`](https://github.com/AnantharamanLab/vRhyme)
+    - [`mash`](https://github.com/marbl/Mash)
+8. Scaffolding of contigs to centroid ([`Minimap2`](https://github.com/lh3/minimap2), [`iVar-consensus`](https://andersen-lab.github.io/ivar/html/manualpage.html))
+9. [Optional] Annotate 0-depth regions with external reference `custom-script`.
+10. Mapping filtered reads to supercontig and mapping constrains([`BowTie2`](http://bowtie-bio.sourceforge.net/bowtie2/),[`BWAmem2`](https://github.com/bwa-mem2/bwa-mem2) and [`BWA`](https://github.com/lh3/bwa))
+11. [Optional] Deduplicate reads ([`Picard`](https://broadinstitute.github.io/picard/) or if UMI's are used [`UMI-tools`](https://umi-tools.readthedocs.io/en/latest/QUICK_START.html))
+12. Variant calling and filtering ([`BCFTools`](http://samtools.github.io/bcftools/bcftools.html),[`iVar`](https://andersen-lab.github.io/ivar/html/manualpage.html))
+13. Create consensus genome ([`BCFTools`](http://samtools.github.io/bcftools/bcftools.html),[`iVar`](https://andersen-lab.github.io/ivar/html/manualpage.html))
+14. Repeat step 10-13 multiple times for the denovo contig route
+15. Contig evaluation and annotation ([`QUAST`](http://quast.sourceforge.net/quast),[`CheckV`](https://bitbucket.org/berkeleylab/checkv/src/master/),[`blastn`](https://blast.ncbi.nlm.nih.gov/Blast.cgi), [`mmseqs-search`](https://github.com/soedinglab/MMseqs2/wiki#batch-sequence-searching-using-mmseqs-search))
+16. Present QC and visualisation for raw read, alignment, assembly, variant calling and consensus calling results ([`MultiQC`](http://multiqc.info/))
 
 ## Usage
 
-> [!NOTE]
-> If you are new to Nextflow and nf-core, please refer to [this page](https://nf-co.re/docs/usage/installation) on how to set-up Nextflow. Make sure to [test your setup](https://nf-co.re/docs/usage/introduction#how-to-run-a-pipeline) with `-profile test` before running the workflow on actual data.
+!!! Note
+    If you are new to Nextflow and nf-core, please refer to [this page](https://nf-co.re/docs/usage/installation) on how to set-up Nextflow. Make sure to [test your setup](https://nf-co.re/docs/usage/introduction#how-to-run-a-pipeline) with `-profile test` before running the workflow on actual data.
 
 Now, you can run the pipeline using:
 
 ```bash
-nextflow run viralgenie/main.nf \
+nextflow run Joon-Klaps/viralgenie \
    -profile <docker/singularity/.../institute> \
    --input samplesheet.csv \
    --outdir <OUTDIR>
 ```
 
-> [!WARNING]
-> Please provide pipeline parameters via the CLI or Nextflow `-params-file` option. Custom config files including those provided by the `-c` Nextflow option can be used to provide any configuration _**except for parameters**_;
-> see [docs](https://nf-co.re/usage/configuration#custom-configuration-files).
+!!! Warning
+     Please provide pipeline parameters via the CLI or Nextflow `-params-file` option. Custom config files including those provided by the `-c` Nextflow option can be used to provide any configuration _**except for parameters**_;
+     see [docs](https://nf-co.re/usage/configuration#custom-configuration-files).
 
-For more details and further functionality, please refer to the [usage documentation](https://nf-co.re/viralgenie/usage) and the [parameter documentation](https://nf-co.re/viralgenie/parameters).
+For more details and further functionality, please refer to the [usage documentation](https://github.io/Joon-klaps/viralgenie/usage) and the [parameter documentation](https://github.io/Joon-klaps/viralgenie/parameters).
 
 ## Credits
 
-viralgenie was originally written by joon.klaps@kuleuven.be.
+Viralgenie was originally written by [`Joon-Klaps`](https://github.com/Joon-Klaps).
 
 We thank the following people for their extensive assistance in the development of this pipeline:
 
 -   [`Philippe Lemey`](https://github.com/plemey)
 -   [`Liana Kafetzopoulou`](https://github.com/LianaKafetzopoulou)
+-   [`nf-core community`](https://nf-co.re/)
 
 <!-- TODO nf-core: If applicable, make list of people who have also contributed -->
 
 ## Contributions and Support
 
-If you would like to contribute to this pipeline, please see the [contributing guidelines](.github/CONTRIBUTING.md).
+If you would like to contribute to this pipeline, please see the [contributing guidelines](https://github.io/Joon-klaps/viralgenie/CONTRIBUTING).
 
 <!--
 For further information or help, don't hesitate to get in touch on the [Slack `#viralgenie` channel](https://nfcore.slack.com/channels/viralgenie) (you can join with [this invite](https://nf-co.re/join/slack)).
@@ -101,7 +109,7 @@ For further information or help, don't hesitate to get in touch on the [Slack `#
 
 <!-- TODO nf-core: Add bibliography of tools and data used in your pipeline -->
 
-An extensive list of references for the tools used by the pipeline can be found in the [`CITATIONS.md`](CITATIONS.md) file.
+An extensive list of references for the tools used by the pipeline can be found in the [`CITATIONS.md`](https://github.io/Joon-klaps/viralgenie/CITATIONS) file.
 
 You can cite the `nf-core` publication as follows:
 

assets/bv-brc-refvirus-anno.withRC.fasta.gz

@@ -6,8 +6,6 @@
 
 ## [Nextflow](https://pubmed.ncbi.nlm.nih.gov/28398311/)
 
-<!-- TODO: Complete the lists of tools -->
-
 > Di Tommaso P, Chatzou M, Floden EW, Barja PP, Palumbo E, Notredame C. Nextflow enables reproducible computational workflows. Nat Biotechnol. 2017 Apr 11;35(4):316-319. doi: 10.1038/nbt.3820. PubMed PMID: 28398311.
 
 ## Pipeline tools

CITATIONS.md docs/CITATIONS.md

@@ -1,24 +1,25 @@
-# nf-core/viralgenie: Contributing Guidelines
+# Joon-Klaps/viralgenie: Contributing Guidelines
 
 Hi there!
-Many thanks for taking an interest in improving nf-core/viralgenie.
 
-We try to manage the required tasks for nf-core/viralgenie using GitHub issues, you probably came to this page when creating one.
+__🤩 Many thanks for taking an interest in improving Viralgenie. 🤩__
+
+We try to manage the required tasks for Viralgenie using GitHub issues, you probably came to this page when creating one.
 Please use the pre-filled template to save time.
 
 However, don't be put off by this template - other more general issues and suggestions are welcome!
 Contributions to the code are even more welcome ;
 
-:::info
-If you need help using or modifying viralgenie then the best place to ask is on the nf-core Slack [Joon-Klaps](https://nfcore.slack.com/team/U043Y6FQR6J).
-:::
+!!! info
+    If you need help using or modifying viralgenie then the best place to ask is on the nf-core Slack [Joon-Klaps](https://nfcore.slack.com/team/U043Y6FQR6J).
+
 
 ## Contribution workflow
 
-If you'd like to write some code for nf-core/viralgenie, the standard workflow is as follows:
+If you'd like to write some code for Joon-Klaps/viralgenie, the standard workflow is as follows:
 
-1. Check that there isn't already an issue about your idea in the [nf-core/viralgenie issues](https://github.com/nf-core/viralgenie/issues) to avoid duplicating work. If there isn't one already, please create one so that others know you're working on this
-2. [Fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) the [nf-core/viralgenie repository](https://github.com/nf-core/viralgenie) to your GitHub account
+1. Check that there isn't already an issue about your idea in the [Joon-Klaps/viralgenie issues](https://github.com/Joon-Klaps/viralgenie/issues) to avoid duplicating work. If there isn't one already, please create one so that others know you're working on this
+2. [Fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) the [Joon-Klaps/viralgenie repository](https://github.com/Joon-Klaps/viralgenie) to your GitHub account
 3. Make the necessary changes / additions within your forked repository following [Pipeline conventions](#pipeline-contribution-conventions)
 4. Use `nf-core schema build` and add any new parameters to the pipeline JSON schema (requires [nf-core tools](https://github.com/nf-core/tools) >= 1.10).
 5. Submit a Pull Request against the `dev` branch and wait for the code to be reviewed and merged
@@ -37,33 +38,32 @@ There are typically two types of tests that run:
 
 ### Lint tests
 
-`nf-core` has a [set of guidelines](https://nf-co.re/developers/guidelines) which all pipelines must adhere to.
-To enforce these and ensure that all pipelines stay in sync, we have developed a helper tool which runs checks on the pipeline code. This is in the [nf-core/tools repository](https://github.com/nf-core/tools) and once installed can be run locally with the `nf-core lint <pipeline-directory>` command.
+`nf-core` has a [set of guidelines](https://nf-co.re/developers/guidelines) which viralgenie adheres to.
+To enforce these and ensure that viralgenie stays in sync, we have developed a helper tool which runs checks on the pipeline code. This is in the [nf-core/tools repository](https://github.com/nf-core/tools) and once installed can be run locally with the `nf-core lint <pipeline-directory>` command.
 
 If any failures or warnings are encountered, please follow the listed URL for more documentation.
 
 ### Pipeline tests
 
-Each `nf-core` pipeline should be set up with a minimal set of test-data.
+Viralgenie is set up with a minimal set of test-data.
 `GitHub Actions` then runs the pipeline on this data to ensure that it exits successfully.
 If there are any failures then the automated tests fail.
 These tests are run both with the latest available version of `Nextflow` and also the minimum required version that is stated in the pipeline code.
 
 ## Patch
 
-:warning: Only in the unlikely and regretful event of a release happening with a bug.
-
--   On your own fork, make a new branch `patch` based on `upstream/master`.
--   Fix the bug, and bump version (X.Y.Z+1).
--   A PR should be made on `master` from patch to directly this particular bug.
+!!! Warning "Only in the unlikely and regretful event of a release happening with a bug."
+    -   On your own fork, make a new branch `patch` based on `upstream/master`.
+    -   Fix the bug, and bump version (X.Y.Z+1).
+    -   A PR should be made on `master` from patch to directly this particular bug.
 
 ## Getting help
 
-For further information/help, please consult the [nf-core/viralgenie documentation](https://nf-co.re/viralgenie/usage) and don't hesitate to get in touch on the nf-core Slack [#viralgenie](https://nfcore.slack.com/channels/viralgenie) channel ([join our Slack here](https://nf-co.re/join/slack)).
+For further information/help, please consult the [Joon-Klaps/viralgenie documentation](https://github.io/Joon-Klaps/viralgenie) and don't hesitate to get in touch on Slack [Joon-Klaps](https://nfcore.slack.com/team/U043Y6FQR6J) channel ([join the nf-core Slack here](https://nf-co.re/join/slack)).
 
 ## Pipeline contribution conventions
 
-To make the nf-core/viralgenie code and processing logic more understandable for new contributors and to ensure quality, we semi-standardise the way the code and other contributions are written.
+To make the Joon-Klaps/viralgenie code and processing logic more understandable for new contributors and to ensure quality, we semi-standardise the way the code and other contributions are written.
 
 ### Adding a new step
 
@@ -113,7 +113,7 @@ This repo includes a devcontainer configuration which will create a GitHub Codes
 
 To get started:
 
--   Open the repo in [Codespaces](https://github.com/nf-core/viralgenie/codespaces)
+-   Open the repo in [Codespaces](https://github.com/Joon-Klaps/viralgenie/codespaces)
 -   Tools installed
     -   nf-core
     -   Nextflow

.github/CONTRIBUTING.md docs/CONTRIBUTING.md

@@ -1,8 +1,15 @@
-# Joon-Klaps/viralgenie: Documentation
+---
+title: Viralgenie
+description: A metagenomics analysis pipeline for eukaryotic viruses written in nextflow
+---
 
-The Joon-Klaps/viralgenie documentation is split into the following pages:
+# ![viralgenie](images/nf-core-viralgenie_logo_dark.png#only-dark)
+# ![viralgenie](images/nf-core-viralgenie_logo_light.png#only-light)
 
--   [Usage](usage.md)
-    -   An overview of how the pipeline works, how to run it and a description of all of the different command-line flags.
--   [Output](output.md)
-    -   An overview of the different results produced by the pipeline and how to interpret them.
+{==
+
+**A metagenomic analysis pipeline for eukaryotic viruses written in nextflow.**
+
+==}
+
+--8<-- "README.md:6:"