MS-Quality-Hub · mwalzer · Mar 22, 2021 · Jul 27, 2020 · Jul 27, 2020 · Oct 31, 2020
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -13,66 +13,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends --no-install-su
   libstdc++6 \
   sudo \
   build-essential \
-  libcurl4-openssl-dev
+  libcurl4-openssl-dev \
+  ssh-client\
+  graphviz
 
 ENV LANG C.UTF-8
 ENV LC_ALL C.UTF-8
 
 RUN echo "deb http://http.debian.net/debian buster main" > /etc/apt/sources.list.d/debian-unstable.list
 
-RUN apt-get install -y --no-install-recommends \
-				r-base \
-				r-recommended \
-				r-cran-devtools \
-				libopenblas-base
 
-#setup R configs
-RUN echo "r <- getOption('repos'); r['CRAN'] <- 'http://cran.us.r-project.org'; options(repos = r);" > ~/.Rprofile
-RUN Rscript -e "install.packages('tidyverse')"
-RUN Rscript -e "install.packages('dplyr')"
-RUN Rscript -e "install.packages('tibble')"
-RUN Rscript -e "install.packages('tidyr')"
-
-RUN Rscript -e "install.packages('ggplot2')"
-RUN Rscript -e "install.packages('graphics')"
-RUN Rscript -e "install.packages('cowplot')"
-RUN Rscript -e "install.packages('ggrepel')"
-RUN Rscript -e "install.packages('lubridate')"
-RUN Rscript -e "install.packages('chron')"
-RUN Rscript -e "install.packages('scales')"
-RUN Rscript -e "install.packages('grid')"
-RUN Rscript -e "install.packages('gridExtra')"
-
-RUN Rscript -e "install.packages('qcc')"
-RUN Rscript -e "install.packages('ggQC')"
-RUN Rscript -e "install.packages('MSQC')"
-RUN Rscript -e "install.packages('IQCC')"
-RUN Rscript -e "install.packages('yhatr')"
-RUN Rscript -e "install.packages('MSstats')"
-RUN Rscript -e "install.packages('pracma')"
-
-RUN Rscript -e "install.packages('anomalize')"
-RUN Rscript -e "install.packages('DMwR')"
-RUN Rscript -e "install.packages('outliers')"
-
-RUN apt-get install -y --no-install-recommends \
-    gfortran \
-    pandoc
-RUN Rscript -e "install.packages('plotly')"
-RUN Rscript -e "install.packages('htmlwidgets')"
-
-#RUN Rscript -e "install.packages('devtools')"
-ENV R_LIBS_USER ~/R/x86_64-pc-linux-gnu/3.5
-ENV R_LIBS_SITE /usr/local/lib/R/site-library:/usr/lib/R/site-library:/usr/lib/R/library
-RUN Rscript -e "install.packages('Rcpp')"
-RUN Rscript -e "library('devtools'); install_github('twitter/AnomalyDetection')"
-
-#RUN echo 'install.packages(c("ggplot2", "plyr", "reshape2", "RColorBrewer", "scales", "FactoMineR", \
-#"Hmisc", "cowplot", "shiny"), repos="http://cran.us.r-project.org", dependencies=TRUE)' > /tmp/packages.R \
-#&& Rscript /tmp/packages.R
-
-
-RUN pip install numpy mypy pronto pytest jupyter rpy2 pyopenms==2.3.* flask
+RUN pip install numpy requests matplotlib pronto jupyter flask matplotlib pytest mypy sphinx
 #RUN pip install -e .  # devcontainer.json: "postCreateCommand": "pip install -e .",
 
 ARG USERNAME=vscode

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -3,7 +3,7 @@
 	"dockerFile": "Dockerfile",
 	"context": "..",
 	"extensions": [
-		"ms-python.python"
+		"ms-python.python", "littlefoxteam.vscode-python-test-adapter", "njpwerner.autodocstring"
 	],
 	"settings": {
 		"python.pythonPath": "/usr/local/bin/python"

diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,7 @@ tests/__pycache__/
 .pytest_cache/
 
 mzqc_pylib.egg-info/
+
+doc/build/**
+
+doc/source/codegen/**
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,25 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: doc/source/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # MZQC python library
 ![](https://github.com/bigbio/mzqc-pylib/workflows/unit-tests/badge.svg)
 ![](https://github.com/bigbio/mzqc-pylib/workflows/release-container/badge.svg)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/bigbio/mzqc-pylib/v0.0.3?filepath=jupyter%2FMZQC_in_5_minutes.ipynb)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/bigbio/mzqc-pylib/v0.1.1?filepath=jupyter%2FMZQC_in_5_minutes.ipynb)
 
 A python library to use mzQC files. Specifically, have a usable object representation of mzQC that can
 * serialise
@@ -16,8 +16,21 @@ pip install -U git+https://github.com/bigbio/mzqc-pylib.git#egg=mzqc-pylib
 ```
 However, we recommend using the [containers](https://quay.io/repository/mwalzer/mzqc-pylib) to check out the latest updates.
 
+## Documentation
+To get a nice and simple overview of how the mzQC-pylib works, visit [here](https://mzqc-pylib.readthedocs.io).
+The code documentation style convention is of the type "Sphinx/numpy".
+If you however have successfully installed the library and want to **jump right in and use the library**, we suggest the [interactive guide](#5min-interactive-guide).
+
+## Development 
+
+### Repository structure
+The python package's code is located in the `mzqc` folder, continuous testing code in `tests`, the documentation in `doc`. The **libray-use** container descriptions are in `containers`, if you want to **develop** for the library with a container, please use the container description within `.devcontainer`.
+
+### Contribution
+Contributions are welcome! (Fork and open PR)
+
 ## MZQC
-Schema see https://github.com/HUPO-PSI/mzQC/
+This library implements python modules for (de-)serialisation and validity checks of the [PSI fileformat mzQC](http://www.psidev.info/groups/quality-control). To see the raw fileformat, including json schema and specification documentation, see https://github.com/HUPO-PSI/mzQC/. **The library follows the formats versioning**(which is 'v(Major).(Minor).(Patch)').
 
 ## 5min interactive guide
-Have a go with our [interactive python notebook](https://mybinder.org/v2/gh/bigbio/mzqc-pylib/v0.0.3?filepath=jupyter%2FMZQC_in_5_minutes.ipynb) to explore what is possible. ([static version](https://github.com/bigbio/mzqc-pylib/blob/master/jupyter/MZQC_in_5_minutes.ipynb))
+Have a go with our [interactive python notebook](https://mybinder.org/v2/gh/bigbio/mzqc-pylib/v0.1.1?filepath=jupyter%2FMZQC_in_5_minutes.ipynb) to explore what is possible. ([static version](https://github.com/bigbio/mzqc-pylib/blob/master/jupyter/MZQC_in_5_minutes.ipynb))
diff --git a/containers/Dockerfile b/containers/Dockerfile
@@ -19,5 +19,5 @@ ENV LC_ALL C.UTF-8
 
 RUN echo "deb http://http.debian.net/debian buster main" > /etc/apt/sources.list.d/debian-unstable.list
 
-RUN pip install numpy pronto jupyter pyopenms==2.3.* requests matplotlib
+RUN pip install numpy requests matplotlib pronto
 RUN pip install -U git+https://github.com/bigbio/mzqc-pylib.git#egg=mzqc-pylib
diff --git a/doc/Makefile b/doc/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)
diff --git a/doc/make.bat b/doc/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/doc/readme.md b/doc/readme.md
@@ -0,0 +1,18 @@
+# Documentation structure
+bootstrap: `sphinx-quickstart`
+N.B. source and build folders are kept separate!
+Edit `doc/source/index.rst`, adding static rst like intro, etc. and code generated class documentation. Use `:glob:` for wildcards.
+Build the from code generated documentation: `sphinx-apidoc -f -o doc/source/codegen mzqc`
+Then, check the doc representation: `sphinx-build doc/source -W -b linkcheck -d _build/doctrees _build`
+And finally, build html with `sphinx-build doc/source _build`
+
+
+
+Writing documentation:
+* https://rest-sphinx-memo.readthedocs.io/en/latest/ReST.html#rest-roles
+* https://build-me-the-docs-please.readthedocs.io/en/latest/Using_Sphinx/UsingGraphicsAndDiagramsInSphinx.html
+* https://stackoverflow.com/questions/9084173/how-to-underline-text-in-restructuredtext
+
+Building:
+* https://docs.readthedocs.io/en/stable/builds.html
+* https://docs.readthedocs.io/en/stable/config-file/v2.html#supported-settings
diff --git a/doc/source/codestructure.rst b/doc/source/codestructure.rst
@@ -0,0 +1,10 @@
+
+Code Structure
+**************
+The library consists of three modules, the syntactic check module, the semantic check module, 
+and the object representation module for (de-)serialisation.
+
+Object Representation Overview
+------------------------------
+
+.. inheritance-diagram:: mzqc.MZQCFile
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -0,0 +1,54 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'mzQC-pylib'
+copyright = '2020, Mathias Walzer'
+author = 'Mathias Walzer'
+
+# The full version, including alpha/beta/rc tags
+release = 'v0.1.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.napoleon', 'sphinx.ext.inheritance_diagram']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -0,0 +1,23 @@
+.. mzQC-pylib documentation master file, created by
+   sphinx-quickstart on Thu Nov  5 13:33:39 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to mzQC-pylib's documentation!
+======================================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+   :glob:
+
+   intro
+   codestructure
+   codegen/modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/source/intro.rst b/doc/source/intro.rst
@@ -0,0 +1,11 @@
+
+Introduction
+************
+
+A python library to creaete and use mzQC files. Specifically, the library facilitates access to mzQC files in form of 
+a **directly usable object representation of mzQC** and offers additional functionality to:
+
+* serialise
+* deserialise
+* syntactic checks
+* semantic checks
diff --git a/environment.yml b/environment.yml
@@ -5,4 +5,5 @@ dependencies:
     - pronto
     - requests 
     - matplotlib
+    - jupyter
     - git+https://github.com/bigbio/mzqc-pylib.git#egg=mzqc-pylib