[WIP] Readthedocs integration

.gitignore

@@ -140,3 +140,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# VS Code
+.vscode/

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .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 OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub

README.md

@@ -1,4 +1,8 @@
-# Next-QC-Flow
+# McQuaC
+
+[![Documentation Status](https://readthedocs.org/projects/mcquac/badge/?version=latest)](https://mcquac.readthedocs.io/en/latest/?badge=latest)
+
+## About McQUaC
 
 This workflow does quality control for DDA mass spectrometry proteomics data. The workflow can be used in two different modes (internal standard evaluation = `isa`).
 
@@ -14,6 +18,10 @@ Bittremieux W, Meysman P, Martens L, Valkenborg D, Laukens K. Unsupervised Quali
 
 The [table](docu/QC_columns_overview.csv) shows all columns which can be retrieved by this quality control workflow, including a brief description for each.
 
+## Getting started
+
+You need to run the workflow with nextflow. For more information see the [documentation](http://mcquac.readthedocs.io/).
+
 ## Usage
 The workflow should be compatible with Linux, MacOS and Windows (WSL2).
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==8.0.2
+sphinx-rtd-theme==3.0.0

docs/source/conf.py

@@ -0,0 +1,35 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'McQuaC'
+copyright = '2024, Ruhr University Bochum, Medizinisches Proteom-Center and Medical Bioinformatics'
+author = 'julianu'
+
+release = '0.1'
+version = '0.1.0'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'

docs/source/index.rst

@@ -0,0 +1,21 @@
+Welcome to McQuaC's documentation!
+===================================
+
+**McQuaC** is a workflow for quality control of DDA mass spectrometry proteomics data. The workflow
+can be used in two different modes...
+
+Check out the :doc:`usage` section for further information, including
+how to :ref:`installation` the project.
+
+.. note::
+
+   This project is under active development.
+
+Contents
+--------
+
+.. toctree::
+
+   index
+   usage
+

docs/source/usage.rst

@@ -0,0 +1,78 @@
+Usage
+=====
+
+The workflow should be compatible with running nextflow on Linux, MacOS and Windows (WSL2).
+
+
+
+.. _requirements:
+Requirements
+------------
+
+* Nextflow
+* Docker
+* `make`
+
+Everything else is maintained within Docker containers.
+
+**TL;DR** Many software projects in academia are abandoned or not updated regularly which makes it
+difficult to use new and old software in a single native environment as they might need different
+version of the same dependency. E.g. thermorawfileparser is actually linked against Mono 5 on Conda
+while fisher_py needs Mono 6 to properly work. This might become worse with more dependencies as
+the workflow matures. Docker container provide a robust way to keep software within their own
+environment while Nextflow manages starting containers, mounting data etc. in a transparent manner.
+
+The use of Docker containers also increases the compatibility between OSs as everything is running
+on Linux (VMs) in the background and enables us to run the workflow on one of Nextflow's many
+distributed executors (K8s, Apptainer, ...).   
+
+There is also at least on library which includes a vendor library and the permission to distribute
+it only via Docker container.
+
+
+.. _installation:
+
+Installation
+------------
+
+Clone the repository
+
+Docker
+^^^^^^
+
+`make docker-imgs` to build/pull the necessary Docker images
+
+
+Run the workflow
+""""""""""""""""
+
+```
+nextflow run -profile docker main.nf --main_raw_spectra_folder <FOLDER_WITH_RAWS_FILES --main_fasta_file <FASTA_FILE> --main_comet_params <COMET_CONFIG> --main_outdir <FOLDER_FOR_RESULTS>
+```
+
+For non-x64-hardware like Apple Silicon (M1, M2) usage
+""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Does not work.
+**TL;DR** Mono is magically detecting it is running on ARM even in Rosetta emulated Docker containers. When correctly entering a x64-specific file it throws a assertion detection as the magically detected host architecture does not match the execution architecture. As Mono is required for ThermoRawFileParser and the Python module `fisher_py` there is currently no chance of getting rid of it. Use a x64 VM in UTM or VirtualBox.
+
+When we get rid of Mono:   
+```
+env DOCKER_DEFAULT_PLATFORM=linux/amd64 nextflow run -profile docker main.nf --main_raw_spectra_folder <FOLDER_WITH_RAWS_FILES --main_fasta_file <FASTA_FILE> --main_comet_params <COMET_CONFIG> --main_outdir <FOLDER_FOR_RESULTS>
+```
+**TL;DR** Some of the used software and containers are only available for x64, therefore Docker writes a warning on stderr that another architecture is used instead of the host architecture, which stops the Nextflow execution. Setting the architecture explicitly using the the env var `DOCKER_DEFAULT_PLATFORM` solves the problems.
+
+
+Run the workflow
+""""""""""""""""
+
+```
+nextflow run main.nf --main_raw_spectra_folder <FOLDER_WITH_RAWS_FILES --main_fasta_file <FASTA_FILE> --main_comet_params <COMET_CONFIG> --main_outdir <FOLDER_FOR_RESULTS>
+```
+
+For non-x64-hardware like Apple Silicon (M1, M2) use
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Does not work, even with Rosetta due to mono. See section Docker
+
+That’s it! You should now be able to execute `main.nf` and all the other workflows within.