Merge pull request #295 from choosehappy/doc_updates

added docker install to readme

Readme.md

@@ -37,7 +37,35 @@ The most basic docker image can be created with the included (7-line) Dockerfile
 
 
 # Installation
+## Using docker
+Docker is now the recommended method for installing and running HistoQC. Containerized runtimes like docker are more portable and avoid issues with python environment management, and ensure reproducible application behavior. Docker is available for Windows, MacOS, and Linux.
 
+>**Note**: These instructions assume you have docker engine installed on your system. If you do not have docker installed, please see the [docker installation instructions](https://docs.docker.com/engine/install/).
+
+1. Begin by pulling the [official HistoQC docker image](https://hub.docker.com/r/histotools/histoqc/tags) from docker hub. This repository contains the latest stable version of HistoQC and is guaranteed up-to-date.
+    ```bash
+    docker pull histotools/histoqc:master
+    ```
+
+1. Next, run the docker image with a few options to mount your data directory and expose the web interface on your host machine.
+
+    ```bash
+    docker run -v <local-path>:/data --name <container-name> -p <local-port>:5000 -it histotools/histoqc:master /bin/bash
+    # Example:
+    # docker run -v /local/datadir:/data --name my_container -p 5000:5000 -it histotools/histoqc:master /bin/bash
+    ```
+
+1. A terminal session will open inside the docker container. You can now run HistoQC as you would on a local machine. 
+
+1. If you exit the shell, the container will stop running but no data/configuration will be lost. You can restart the container and resume your work with the following command:
+
+    ```bash
+    docker start -i <container-name>
+    # Example:
+    # docker start -i my_container
+    ```
+
+## Using pip
 You can install HistoQC into your system by using 
 
 ```bash
@@ -110,8 +138,6 @@ optional arguments:
   -h, --help   show this help message and exit
   --list       list available configs
   --show NAME  show named example config
-  
-  
 ```
 
 
@@ -129,43 +155,28 @@ HistoQC now has a httpd server which allows for improved result viewing, it can
 
 ```
 C:\Research\code\HistoQC>python -m histoqc.ui --help
-usage: __main__.py [-h] [--bind ADDRESS] [--port PORT] [--deploy OUT_DIR]
-                   [data_directory]
+usage: histoqc.ui [-h] [--port PORT] resultsfilepath
+
+launch server for result viewing in user interface
 
 positional arguments:
-  data_directory        Specify the data directory [default:current directory]
+  resultsfilepath       Specify the full path to the results file. The user must specify this path.
 
 optional arguments:
   -h, --help            show this help message and exit
-  --bind ADDRESS, -b ADDRESS
-                        Specify alternate bind address [default: all
-                        interfaces]
-  --port PORT           Specify alternate port [default: 8000]
-  --deploy OUT_DIR      Write UI to OUT_DIR
-
+  --port PORT, -p PORT  Specify the port [default:5000]
 ```
 
-After completion of slide processing, view results in your web-browser simply by running the following command *from within the output directory* (saved in the **histoqc_output_YYMMDD-hhmmss** format by default. See histoqc CLI -o option)
-
-```bash
-cd histoqc_output_YYMMDD-hhmmss
-python -m histoqc.ui 
-```
+After completion of slide processing, view results in your web-browser by running the following command:
 
-... OR set data_directory to the output directory explicitly:
 ```bash
-python -m histoqc.ui ./histoqc_output_YYMMDD-hhmmss
-```
-
-Which will likely say something like:
-```
-HistoQC data directory: 'D:\temp\HistoQC'
-Serving HistoQC UI on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+python -m histoqc.ui <results-file-path>
+# Example:
+# python -m histoqc.ui ./histoqc_output_YYMMDD-hhmmss/results.tsv
 ```
+>**Note**: The results file is a tab-separated file generated by HistoQC containing the quality control metrics for each slide. HistoQC generates the results file in the output directory specified by the `-o` flag, or formatted as `histoqc_output_YYMMDD-hhmmss` by default.
 
-Allowing you to browse to http://localhost:8000/ to select your results.tsv file.
-
-This can also be done remotely, but is a bit more complex, see advanced usage.
+You may then navigate to `http://<hostname>:5000` in your web browser to view the results.
 
 # Configuration modifications