From 7c3335f7c81a5f30dc1b6f55c5cc858c35f17981 Mon Sep 17 00:00:00 2001
From: Frederick Muriuki Muriithi
Date: Mon, 9 May 2022 05:20:53 +0300
Subject: Update documentation and license

Add documentation on how to run the development version of the
GeneNetwork Quality Control application.

Update the license to the agpl3+ license used by genenetwork3
---
 README.org | 79 ++++++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 61 insertions(+), 18 deletions(-)

(limited to 'README.org')

diff --git a/README.org b/README.org
index ecf7815..8162617 100644
--- a/README.org
+++ b/README.org
@@ -1,5 +1,5 @@
 #+STARTUP: inlineimages
-#+TITLE: Quality Control Application
+#+TITLE: GeneNetwork Quality Control Application
 
 ** Project Goals
 
@@ -29,13 +29,59 @@ following criteria:
 
 For reproducibility, this project is developed using guix.
 
-To launch a guix shell for development, do:
+To launch a guix shell for development, do
+#+BEGIN_SRC shell
+  guix shell --container --network --pure --manifest=manifest.scm --share=/some/host/directory=/the/upload/directory
+#+END_SRC
+which environment that is isolated from the rest of your system.
+
+We share a host directory with the container (that is writeable by the user that
+started the web application) to serve as the upload directory for the
+application.
 
+*** Run the CLI version
+
+To run the CLI version of the application, we need to set up the correct ~PYTHONPATH~
+#+BEGIN_SRC shell
+export PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}$(pwd)"
+#+END_SRC
+which enables us to run the script with
 #+BEGIN_SRC shell
-  guix shell --container --network --manifest=manifest.scm
+python3 scripts/qc.py --help
 #+END_SRC
 
-to get an environment that is isolated from the rest of your system.
+Without setting up the ~PYTHONPATH~ environment variable, you might get an error
+like the following
+#+BEGIN_EXAMPLE shell
+$ python3 scripts/qc.py --help
+Traceback (most recent call last):
+  File "/home/frederick/genenetwork/gnqc_py/scripts/qc.py", line 8, in <module>
+    from quality_control.errors import ParseError
+ModuleNotFoundError: No module named 'quality_control'
+#+END_EXAMPLE
+
+*NOTE*: Setting up the ~PYTHONPATH~ environment variable is only necessary for
+the development environment. It *MUST NOT* require that the end-user set this up
+at all!
+
+*** Run the web version
+
+To run the web-version of the qc app in development mode, you need to set up a
+few environment variables
+#+BEGIN_SRC shell
+export FLASK_APP=wsgi.py
+export FLASK_ENV=development
+export QCAPP_INSTANCE_PATH=/path/to/directory/with/config.py
+#+END_SRC
+then you can run the application with
+#+BEGIN_SRC shell
+flask run
+#+END_SRC
+
+You then need to manually start the *rq* worker(s)
+#+BEGIN_SRC shell
+rq worker qcapp_queue
+#+END_SRC
 
 *** Checks
 
@@ -56,23 +102,23 @@ To check for correct type usage in the application, run:
 
 ** Running QC
 
-*** Command-Line Version
+*** Installing QC
 
-Clone this repository
+The application can be installed using guix by pointing to the [[./guix.scm][guix.scm]] file as
+follows:
 #+BEGIN_SRC shell
-  git clone http://git.genenetwork.org/fredmanglis/gnqc_py.git
-#+END_SRC
-then install the application
-#+BEGIN_SRC shell
-  $ python3 -m venv .venv
-  $ source .venv/bin/activate
-  (.venv) $ pip install .
+guix package [-p /path/to/qc/profile] -f guix.scm
 #+END_SRC
 
+Once installed, the sections that follow show how to use the *qc* application
+
+*** Command-Line Version
+
+Install the application as shown in the [[Installing QC]] section above.
 
 To run qc against a file, the syntax is:
 #+BEGIN_SRC shell
-  python3 -m qc [--strainsfile <strainsfile-path>] [--verbose] <filetype> <filepath>
+ qc [--strainsfile <strainsfile-path>] [--verbose] <filetype> <filepath>
 #+END_SRC
 where
 - ~<filetype>~ is one of "*average*" or "*standard-error*"
@@ -85,12 +131,9 @@ where
 
 To view the usage information for the application, run
 #+BEGIN_SRC shell
-  python3 -m qc --help
+qc --help
 #+END_SRC
 
-**** TODO Figure out how to put qc.py in a /bin or /scripts directory and still be able to import the modules in the repo
-**** TODO Reduce the command to simply ~qc [--strainsfile <strainsfile-path>] [--verbose] <filetype> <filepath>~
-
 *** Web Version
 
 Coming soon...
-- 
cgit v1.2.3