docs: update etiquette (#1232)

* refactor: Remove Balsamic container (#1220)

* add cadd container

* changelog

* remove second update command

* add cadd to github actions

* add tabix to container test

* remove tabix from container

* remove tabix from container tests

* add header

* add cadd to cache and tests

* refactor docker recipe

* refactor download and extract repo

* add container etiquette

* add container etiquette to docs

* remove sphinxcontrib-napoleon==0.7

* remove sphinxcontrib

* fix deps and URLs

* refactor etiquette

---------

Co-authored-by: Vadym <vadym.ivanchuk@scilifelab.se>

CHANGELOG.rst

@@ -13,6 +13,7 @@ Added:
 * Support singularity bind paths with different destination directories https://github/Clinical-Genomics/BALSAMIC/pull/1211
 * Added `--rerun-trigger mtime` option to Snakemake command https://github.com/Clinical-Genomics/BALSAMIC/pull/1217
 * `CADD` container https://github.com/Clinical-Genomics/BALSAMIC/pull/1222
+* `Container ettiquette` to ReadtheDocs https://github.com/Clinical-Genomics/BALSAMIC/pull/1132
 
 Changed:
 ^^^^^^^^
@@ -36,7 +37,7 @@ Fixed:
 * Broken documentation links https://github.com/Clinical-Genomics/BALSAMIC/pull/1226
 
 Removed:
-^^^^^^^
+^^^^^^^^
 * Config folder https://github.com/Clinical-Genomics/BALSAMIC/pull/1175
 * Balsamic container https://github.com/Clinical-Genomics/BALSAMIC/pull/1230
 

docs/README.rst

@@ -15,6 +15,7 @@ Install Sphinx and extensions:
 
 .. code-block::
 
+   cd /path/to/BALSAMIC
    python -m pip install --upgrade --upgrade-strategy eager --no-cache-dir .
    cd docs
    pip install -r requirements.txt -r ../requirements-dev.txt

docs/bioinfo_softwares.rst

@@ -8,7 +8,7 @@ one is included: usage and parameters, and relevant external links.
 ascatNgs
 ~~~~~~~~
 :Source code: `GitHub` `<https://github.com/cancerit/ascatNgs>`_
-:Article: `PNAS` `<https://doi.org/10.1073/pnas.1009843107>`_
+:Article: `PNAS` `<https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6097604/>`_
 :Version: `4.5.0`
 
 bcftools
@@ -32,7 +32,7 @@ bwa
 cnvkit
 ~~~~~~
 :Source code: `GitHub` `<https://github.com/etal/cnvkit>`_
-:Article: `PLOS Computational Biology` `<http://dx.doi.org/10.1371/journal.pcbi.1004873>`_
+:Article: `PLOS Computational Biology` `<https://doi.org/10.1371/journal.pcbi.1004873>`_
 :Version: `0.9.9`
 
 delly
@@ -56,7 +56,7 @@ fastp
 fastqc
 ~~~~~~
 :Source code: `GitHub` `<https://github.com/s-andrews/FastQC>`_
-:Article: `Babraham` `<http://www.bioinformatics.babraham.ac.uk/projects/fastqc/>`_
+:Article: `Babraham` `<https://www.bioinformatics.babraham.ac.uk/projects/fastqc/>`_
 :Version: `0.11.9`
 
 gatk
@@ -80,7 +80,7 @@ multiqc
 mosdepth
 ~~~~~~~~
 :Source code: `GitHub` `<https://github.com/brentp/mosdepth>`_
-:Article: `Bioinformatics` `<https://academic.oup.com/bioinformatics/article/34/5/867/4583630?login=true>`_
+:Article: `Bioinformatics` `<https://doi.org/10.1093/bioinformatics/btx699>`_
 :Version: `0.3.3`
 
 picard

docs/conf.py

@@ -18,8 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "BALSAMIC"
-copyright = "2020, Hassan Foroughi Asl"
-author = "Hassan Foroughi Asl"
+copyright = "2023, Clinical Genomics"
 
 # -- General configuration ---------------------------------------------------
 

docs/index.rst

@@ -33,8 +33,7 @@
     :hidden:
     :maxdepth: 1
 
-    git_etiquette
-    snakemake_etiquette
     README
+    programming_guide
     semver
     FAQs

docs/snakemake_etiquette.rst → docs/programming_guide.rst

@@ -1,4 +1,60 @@
-===================
+===========
+Etiquettes
+===========
+
+* Structure the code properly
+* Maintain good and consistent naming convention
+* Keep it Simple
+* Don’t repeat yourself
+
+
+Git etiquette
+=============
+
+**Code formatting**
+^^^^^^^^^^^^^^^^^^^
+
+BALSAMIC is using Black as code formatter: https://github.com/psf/black
+
+**Conventional commits and PRs**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PRs should follow the following keywords in the title: https://www.conventionalcommits.org/en/v1.0.0/
+
+Commit messages are recommended to following the following similar to PRs:
+
+#. **feat**: Introducing a new features. This includes but not limited to workflows, SnakeMake rule, cli, and plugins. In other words, anything that is new and fundamental change will also go here. Enhancements and optimizations will go into refactor.
+#. **fix**: This is essentially a patch. Included but not limited to: bug fixes, hotfixes, and any patch to address a known issue.
+#. **doc**: Any changes to the documentation are part of doc subject line, included but not limited to docstrings, cli-help, readme, tutorial, documentation, CHANGELOG, and addition of ipython/jupyter notebook in the form of tutorial.
+#. **test**: Any changes to the tests are part of test subject line. This includes adding, removing or updating of the following: unittests, validation/verification dataset, and test related configs.
+#. **refactor**: Refactoring refers to a rather broad term. Any style changes, code enhancement, and analysis optimization.
+#. **version**: Any changes to .bumpversion config and or change of version will be specified with this. This includes comments within .bumpversion, structure of .bumpversion, etc.
+
+**Scope**
+^^^^^^^^^
+
+Scope is specified within parenthesis. It show the *scope* of the subject line. The following scope are valid:
+
+* cli
+* style
+* rule (refers to SnakeMake rules)
+* workflow (refer to SnakeMake workflows)
+* config (refers to configs that are either used or generated by BALSAMIC)
+* Relevant scopes that might fit into a scope description
+
+Note: If scope is broad or matching with multiple (it shouldn't, but if it does) one can leave out the scope.
+
+**Message**
+^^^^^^^^^^^
+
+It's better to start Git commit message with the following words:
+
+* added
+* removed
+* updated
+
+
+
 Snakemake etiquette
 ===================
 
@@ -103,3 +159,47 @@ Similarly ``awk`` or ``R`` external scripts can be saved in ``assets/scripts/*aw
 
 1. https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html
 2. https://snakemake.readthedocs.io/en/stable/snakefiles/writing_snakefiles.html
+
+
+
+Container etiquette
+===================
+
+BALSAMIC uses singularity containers to perform the bioinformatics analysis. These containers are built using Docker and pushed to Docker Hub.
+For more details on building containers using docker, please refer to the official docker documentation: https://docs.docker.com/
+
+**Structure of Docker recipe**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    FROM <CONTAINER>:<VERSION>
+
+    LABEL base.image="<CONTAINER>:<VERSION>"
+    LABEL maintainer="Clinical Genomics"
+    LABEL about.contact="support@clinicalgenomics.se"
+    LABEL software="<NAME_OF_THE_MAIN_SOFTWARE>"
+    LABEL software.version="<VERSION_OF_THE_MAIN_SOFTWARE>"
+    LABEL about.summary="<DESCRIPTION_OF_THE_MAIN_SOFTWARE>"
+    LABEL about.home="<URL_OF_THE_MAIN_SOFTWARE>""
+    LABEL about.documentation="<DOCS_URL_OF_THE_MAIN_SOFTWARE>"
+    LABEL about.license="MIT License (MIT)"
+
+    RUN apt-get update && apt-get -y upgrade && \
+        apt-get -y install --no-install-recommends && \
+        <SOFTWARE_1 SOFTWARE_2> && \
+        apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+    RUN ....
+
+    USER    ubuntu
+    WORKDIR /home/ubuntu
+    CMD ["/bin/bash"]
+
+
+It is preferable to:
+    * Use official image as the base
+    * Use Ubuntu-LTS as the base image
+    * Avoid Conda unless necessary
+    * Add versions
+    * Avoid building containers with multiple software used in the rules

docs/requirements.txt

@@ -1,10 +1,11 @@
 appdirs==1.4.4
-configargparse==1.5.3
-docutils>=0.14,<0.18
+configargparse==1.7
+docutils==0.18.1
 recommonmark==0.7.1
-sphinx==4.2.0
-sphinx-argparse==0.3.1
+sphinx==6.2.1
+sphinx-argparse==0.4.0
 sphinx-click==3.0.2
-sphinx_rtd_theme==1.0.0
-furo==2021.10.9
+sphinx_rtd_theme==1.2.2
+furo==2023.7.26
 cyvcf2
+

docs/resources.rst

@@ -25,6 +25,7 @@ References and other resources
 #. **dbVar**: dbVar is NCBI's database of genomic structural variation – insertions, deletions, duplications, inversions, mobile element insertions, translocations, and complex chromosomal rearrangements https://www.ncbi.nlm.nih.gov/dbvar Download link: https://www.ncbi.nlm.nih.gov/dbvar/content/ftp_manifest/
 #. **Drug sensitivity in cancer**: Identifying molecular features of cancers that predict response to anti-cancer drugs. http://www.cancerrxgene.org/ Download link: ftp://ftp.sanger.ac.uk/pub4/cancerrxgene/releases
 #. **VarSome**: VarSome is a knowledge base and aggregator for human genomic variants. https://varsome.com/about/
+#. **CADD**\ : CADD is a tool for scoring the deleteriousness of single nucleotide variants as well as insertion/deletions variants in the human genome. CADD can quantitatively prioritize functional, deleterious, and disease causal variants across a wide range of functional categories, effect sizes and genetic architectures and can be used prioritize causal variation in both research and clinical settings.
 
 Sample datasets
 ---------------

docs/semver.rst

@@ -13,7 +13,6 @@ Since October 24, 2018 the following changes were added in addition to SemVer al
     callers, aligners, quality trimmers, and/or anything other than QC reporting and rule `all`.
 
   - Addition of annotation softwares or sources, variant callers, aligners, quality trimmers, and/or anything other than QC reporting
-
 
 - **minor**:
 

setup.py

@@ -35,7 +35,6 @@
     "cyvcf2==0.30.22",
     "datrie==0.8.2",
     "defusedxml==0.7.1",
-    "docutils==0.20.1",
     "dpath==2.1.6",
     "fasteners==0.18",
     "fastjsonschema==2.18.0",