Merge pull request #61 from uab-cgds-worthey/restructure_docs

Restructure docs and host using ReadTheDocs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+# template modelled after https://github.com/snakemake/snakemake
+---
+
+**QuaC version**
+<!--Note the QuaC version for which you experience the bug.-->
+
+**Describe the bug**
+<!--A clear and concise description of what the bug is.-->
+
+**Logs**
+<!--If applicable, any terminal output to help explain your problem.-->
+
+**Minimal example**
+<!--Adding a minimal example for reproducing the bug would help.-->
+
+**Additional context**
+<!--Add any other context about the problem here.-->

.gitlab/merge_request_templates/MERGE_REQUEST_TEMPLATE.md → .github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -1,4 +1,4 @@
-# Merge request
+# Pull request
 
 Please fill in the checklist below and comment as needed.
 
@@ -12,4 +12,4 @@ Please fill in the checklist below and comment as needed.
 - [ ] Updated `Changelog.md` file with change logs in recommended format?
 
 
-### Anything else reviewer should know?
+## Anything else reviewer should know?

.github/workflows/action.yml

@@ -0,0 +1,10 @@
+name: Check Markdown links
+
+on: push
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+mkdocs:
+  configuration: mkdocs.yaml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: configs/mkdocs/requirements.txt

configs/mkdocs/mkdocs.yaml

@@ -0,0 +1,8 @@
+name: mkdocs
+
+channels:
+  - conda-forge
+
+dependencies:
+  - python=3.10
+  - mkdocs=1.4.2

configs/mkdocs/requirements.txt

@@ -0,0 +1,66 @@
+#
+# This file is autogenerated by pip-compile with python 3.10
+# To update, run:
+#
+#    pip-compile docs/requirements.in
+#
+click==8.1.3
+    # via mkdocs
+ghp-import==2.1.0
+    # via mkdocs
+griffe==0.22.0
+    # via mkdocstrings-python
+importlib-metadata==4.12.0
+    # via mkdocs
+jinja2==3.1.2
+    # via
+    #   mkdocs
+    #   mkdocstrings
+markdown==3.3.7
+    # via
+    #   markdown-include
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocstrings
+    #   pymdown-extensions
+markdown-include==0.6.0
+    # via -r docs/requirements.in
+markupsafe==2.1.1
+    # via
+    #   jinja2
+    #   mkdocstrings
+mergedeep==1.3.4
+    # via mkdocs
+mkdocs==1.3.0
+    # via
+    #   -r docs/requirements.in
+    #   mkdocs-autorefs
+    #   mkdocstrings
+mkdocs-autorefs==0.4.1
+    # via mkdocstrings
+mkdocstrings[python]==0.19.0
+    # via
+    #   -r docs/requirements.in
+    #   mkdocstrings-python
+mkdocstrings-python==0.7.1
+    # via mkdocstrings
+packaging==21.3
+    # via mkdocs
+pymdown-extensions==9.5
+    # via mkdocstrings
+pyparsing==3.0.9
+    # via packaging
+python-dateutil==2.8.2
+    # via ghp-import
+pyyaml==6.0
+    # via
+    #   mkdocs
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
+six==1.16.0
+    # via python-dateutil
+watchdog==2.1.9
+    # via mkdocs
+zipp==3.8.0
+    # via importlib-metadata

configs/workflow.yaml

@@ -1,14 +1,16 @@
 datasets:
     # path to ref genome
     ref: "/data/project/worthey_lab/datasets_central/human_reference_genome/processed/GRCh38/no_alt_rel20190408/GCA_000001405.15_GRCh38_no_alt_analysis_set.fna"
-    # path to Somalier dataset dependencies
+    # path to Somalier dataset dependencies. Available at https://github.com/brentp/somalier
     somalier:
         sites: "/data/project/worthey_lab/manual_datasets_central/somalier/0.2.13/sites/sites.hg38.vcf.gz"
         labels_1kg: "/data/project/worthey_lab/manual_datasets_central/somalier/0.2.13/ancestry/ancestry-labels-1kg.tsv"
         somalier_1kg: "/data/project/worthey_lab/manual_datasets_central/somalier/0.2.13/ancestry/1kg-somalier/"
     # path to verifyBamID dataset dependencies
     verifyBamID:
+        # Refer to https://github.com/Griffan/VerifyBamID for downloading this file
         svd_dat_wgs: "/data/project/worthey_lab/manual_datasets_central/verifyBamID/2.0.1/resource/wgs/1000g.phase3.100k.b38.vcf.gz.dat"
+        # Refer to QuaC docs to create this file. See section "Prepare verifybamid datasets for exome mode" in how to run quac
         svd_dat_exome: "/data/project/worthey_lab/manual_datasets_central/verifyBamID/2.0.1/resource/exome/chr_added/1000g.phase3.10k.b38.exome.vcf.gz.dat"
 
 #### hardware resources ####

docs/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing Guidelines
+
+:grin: :tada: Thank you for taking the time to contribute! :grin: :tada:
+
+The following is a set of guidelines for contributing to QuaC.
+
+- [Contributing Guidelines](#contributing-guidelines)
+  - [Contributing](#contributing)
+  - [Reporting Issues](#reporting-issues)
+  - [Seeking Support](#seeking-support)
+
+---
+
+## Contributing
+
+To get started on contributing to QuaC:
+
+- Follow [Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
+- Read these **Contributing Guidelines** to completion
+- Choose an existing feature/bug listed under [issues](https://github.com/uab-cgds-worthey/quac/issues). If the
+  feature/bug is not listed under issues, create a new issue.
+- Fork and create a new branch for your work.
+- Submit a pull request with adequate documentation of functionality and changes made. Ensure the PR description clearly
+describes the problem and solution. Include the relevant issue number.
+
+## Reporting Issues
+
+If you encounter a bug while using the project, we want to hear about it! Here's how to report a bug:
+
+  1. Check the [existing issues](https://github.com/uab-cgds-worthey/quac/issues) to see if the bug has already been
+   reported.
+  2. If the bug has not already been reported, create a new issue by clicking the "New Issue" button on the [issues
+   page](https://github.com/uab-cgds-worthey/quac/issues) and click "Get started" for a "🐞 Bug Report".
+  3. In the 🐞 Bug Report template, provide a clear and concise description of the bug, including any error messages
+   that you encountered and steps to reproduce the bug in a specific environment.
+  4. If possible, include any relevant details such as the version of the project you are using, your operating system,
+   and any other relevant information that may help to reproduce and fix the bug.
+
+---
+
+## Seeking Support
+
+For support in setting up and using QuaC, please contact us via [GitHub
+Issues](https://github.com/uab-cgds-worthey/quac/issues).

Changelog.md → docs/Changelog.md

@@ -12,39 +12,35 @@ YYYY-MM-DD  John Doe
 ```
 ---
 
-2021-03-16  Manavalan Gajapathy
+2023-01-31  Manavalan Gajapathy
 
-* Creates QuaC workflow, which can run somalier, mosdepth, indexcov, covviz and verifybamid2
-* Uses pedigree file as input
-* Makes it production ready.
+Restructures the docs to make it clearer to non-Cheaha users, updates documentation to reflect recent CLI option changes, and hosts docs publicly using readthedocs.
 
-2021-05-28  Manavalan Gajapathy
+* `Readme.md` has grown bigger and became difficult to navigate. Especially for non-Cheaha users. So documentation in readme.md is now restructured to break into multiple files and is now easier to consume.
+     * Makes the doc generic to non-Cheaha users
+     * Identifies parts of the docs that are specific to Cheaha or CGDS users
+* Updates doc to reflect changes made in #59 
+* Now hosts doc for "Sample QC review system".
+* Uses [mkdocs](https://www.mkdocs.org/) to create static site for documentation.
+* Hosts QuaC docs using [ReadTheDocs](https://readthedocs.org/) 
+* Migrates Gitlab MR template to Github PR template
+* Adds github action to identify broken links in markdown files
 
-* QuaC is heavily reworked to be a companion pipeline to small variant caller pipeline and will now perform most of the
-  QC analyses for WGS/WES data. While the small caller pipeline will still run few QC tools (for pragmatic reasons),
-  QuaC will now take over the heavylifting of QC, including the QC-checkup, which is now called as QuaC-Watch.
-* Runs in containerized environment using Singularity.
-* QuaC can perform both sample-level and project-level QC. This is the major reason why it was decided to separate QC from small-variant caller pipeline, as it could only perform single-sample QC.
-* More QC tools were added
-* For QC checkup (ie. QuaC-Watch), QuaC now heavily expands to vcf metrics and adds significant amount of QC thresholds for bam metrics.
-* QuaC's input are output from the small variant caller pipeline, and former's output will fit seemlessly with the latter's output.
-* QuaC accepts pedigree file as input. A dummy pedigree file creator script is provided, which will be handy until phenotips is made available to us.
-* System-level testing is added
-
-2021-06-08  Manavalan Gajapathy
 
-* Bugfix: Fixes error when there is only one sample in input ped file (#34)
-* Adds system-testing for such only-one-sample-in-input setup (#35).
-
-2022-04-07  Manavalan Gajapathy
+2023-01-27  Manavalan Gajapathy
 
-* Previously hardcoded hardware resources for snakemake rules can now be supplied via `configs/workflow.yaml` (closes #48)
-* Modified multiqc conda env config to use explicit dependencies to get around installation issues (closes #47)
+In efforts to make the repo generic to non-cheaha users, following changes were made:
 
+* Removes default quac_watch_config as it can lead to errors (#39)
+* Makes slurm schedule as dependency; now quac can be run locally. Local run is the default and `--use_slurm` allows
+  running snakemake-triggered jobs in slurm. (#57)
+* Allows users to define custom slurm partitions and time limits via workflow configs (#58)
+* Updates median insert size threshold in quac-watch config (#54)
 
 2023-01-20  Manavalan Gajapathy
 
-As part of making QuaC publicly available, following updates were made to make it more generic to the environment and user friendly:
+As part of making QuaC publicly available, following updates were made to make it more generic to the environment and
+user friendly:
 
 * Removes prerun QC from small variant caller pipeline as requirement to QuaC (closes #45)
 * Explicitly defines conda environments (closes #49)
@@ -54,11 +50,39 @@ As part of making QuaC publicly available, following updates were made to make i
 * Uses minimal snakemake instead of full-featured snakemake (closes #56)
 
 
-2023-01-27  Manavalan Gajapathy
+2022-04-07  Manavalan Gajapathy
 
-In efforts to make the repo generic to non-cheaha users, following changes were made:
+* Previously hardcoded hardware resources for snakemake rules can now be supplied via `configs/workflow.yaml` (closes
+  #48)
+* Modified multiqc conda env config to use explicit dependencies to get around installation issues (closes #47)
 
-* Removes default quac_watch_config as it can lead to errors (#39)
-* Makes slurm schedule as dependency; now quac can be run locally. Local run is the default and `--use_slurm` allows running snakemake-triggered jobs in slurm. (#57)
-* Allows users to define custom slurm partitions and time limits via workflow configs (#58)
-* Updates median insert size threshold in quac-watch config (#54)
+
+2021-06-08  Manavalan Gajapathy
+
+* Bugfix: Fixes error when there is only one sample in input ped file (#34)
+* Adds system-testing for such only-one-sample-in-input setup (#35).
+
+
+2021-05-28  Manavalan Gajapathy
+
+* QuaC is heavily reworked to be a companion pipeline to small variant caller pipeline and will now perform most of the
+  QC analyses for WGS/WES data. While the small caller pipeline will still run few QC tools (for pragmatic reasons),
+  QuaC will now take over the heavylifting of QC, including the QC-checkup, which is now called as QuaC-Watch.
+* Runs in containerized environment using Singularity.
+* QuaC can perform both sample-level and project-level QC. This is the major reason why it was decided to separate QC
+  from small-variant caller pipeline, as it could only perform single-sample QC.
+* More QC tools were added
+* For QC checkup (ie. QuaC-Watch), QuaC now heavily expands to vcf metrics and adds significant amount of QC thresholds
+  for bam metrics.
+* QuaC's input are output from the small variant caller pipeline, and former's output will fit seemlessly with the
+  latter's output.
+* QuaC accepts pedigree file as input. A dummy pedigree file creator script is provided, which will be handy until
+  phenotips is made available to us.
+* System-level testing is added
+
+
+2021-03-16  Manavalan Gajapathy
+
+* Creates QuaC workflow, which can run somalier, mosdepth, indexcov, covviz and verifybamid2
+* Uses pedigree file as input
+* Makes it production ready.

docs/index.md

@@ -0,0 +1 @@
+{!README.md!}