Populate initial user guide docs

gigony · gigony · commit e45709cae444 · 2021-09-15T03:27:51.000-07:00
Signed-off-by: Gigon Bae &lt;gbae@nvidia.com&gt;
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -61,26 +61,37 @@ h1 {
 /* Code Highlight */
 div[class^="highlight"] pre {
     color: rgb(248, 248, 242);
-    background-color: rgb(35, 50, 74);
+    background-color: rgb(41, 44, 46);
     border: 0px;
     box-shadow: none;
 }
+div.highlight{
+    border-radius: 5px;
+}
+div.highlight pre {
+    border-radius: 5px;
+}
+div.cell div.cell_input div.highlight {
+    border-radius: 0px;
+}
+
+/* Code Block Caption */
+div.code-block-caption {
+    font-weight: bold;
+    font-style: italic;
+}
+
+/* Code Line Highlight */
+.highlight .hll {
+    background-color: rgb(133, 132, 24);
+}
 
 /* Left bar color for cells in Jupyter Notebook */
 div.cell div.cell_input {
-    border-left-color: rgb(93, 193, 183)
+    border-left-color: rgb(127, 218, 255)
 }
 
-/* .highlight-bash pre {
-    color: rgb(248, 248, 242);
-    background-color: rgb(35, 50, 74);
-    border: 0px;
-    box-shadow: none;
+/* Code highlight in source code view */
+.viewcode-block:target {
+    background-color: #382927;
 }
-
-.highlight-default pre {
-    color: rgb(248, 248, 242);
-    background-color: rgb(35, 50, 74);
-    border: 0px;
-    box-shadow: none;
-} */
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -30,3 +30,4 @@ sphinxcontrib-htmlhelp
 sphinxcontrib-jsmath
 sphinxcontrib-qthelp
 sphinxcontrib-serializinghtml
+sphinxcontrib-mermaid
diff --git a/docs/source/_templates/navbar-logo.html b/docs/source/_templates/navbar-logo.html
@@ -24,4 +24,4 @@
 <a class="navbar-brand" href="{{ pathto(master_doc) }}">
   <p class="title">{{ project }}</p>
 </a>
-{% endif %}
+{% endif %}
diff --git a/docs/source/_templates/sidebar-quicklinks.html b/docs/source/_templates/sidebar-quicklinks.html
@@ -2,8 +2,8 @@
     <h5 class="card-header font-weight-bold">Version {{ release }}</h5>
     <div class="card-body">
         <ul class="list-group list-group-flush list-unstyled quicklinks">
-            <li><a href="{{ pathto('getting_started/tutorials/index.html', 1) }}"><i class="text-muted fas fa-book fa-fw"></i> Tutorials</a></li>
-            <li><a href="{{ pathto('release_notes/v' + version + '.html', 1) }}"><i class="text-muted fas fa-newspaper fa-fw"></i> Changelog</a></li>
+            <li><a href="{{ pathto('release_notes/v' + version + '.html', 1) }}"><i class="text-muted fas fa-newspaper fa-fw"></i> What's New</a></li>
+            <li><a href="{{ pathto('getting_started/tutorials/index.html', 1) }}"><i class="text-muted fas fa-book fa-fw"></i> Tutorials</a></li>            
             <li><a href="{{ pathto('https://github.com/Project-MONAI/monai-deploy-app-sdk/issues/new/choose', 1) }}"><i class="text-muted fas fa-question-circle fa-fw"></i> Get help</a></li>
             <li><a href="{{ pathto('introduction/contributing.html', 1) }}"><i class="text-muted fas fa-code-branch fa-fw"></i> Contribute</a></li>
         </ul>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -34,8 +34,7 @@
 # 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 = []  # type: ignore
-
+exclude_patterns = ["_build"]  # type: ignore
 
 # -- General configuration ---------------------------------------------------
 
@@ -67,12 +66,17 @@
     # https://myst-parser.readthedocs.io/en/latest/sphinx/use.html#automatically-create-targets-for-section-headers
     # "sphinx.ext.autosectionlabel",  <== don't need anymore from v0.13.0
     "sphinx_autodoc_typehints",
+    "sphinxcontrib.mermaid",
 ]
 
 autoclass_content = "both"
 add_module_names = True
 source_encoding = "utf-8"
-autosectionlabel_prefix_document = True
+# Prefix document path to section labels, to use:
+# `path/to/file:heading` instead of just `heading`
+# (https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html)
+# autosectionlabel_prefix_document = True
+# autosectionlabel_maxdepth = 4
 napoleon_use_param = True
 napoleon_include_init_with_doc = True
 set_type_checking_flag = True
@@ -182,14 +186,14 @@
     "dollarmath",
     "html_admonition",
     "html_image",
-    "linkify",
+    # "linkify",  # disable linkify to not confuse with the file name such as `app.py`
     "replacements",
     # "smartquotes",
     "substitution",
     "tasklist",
 ]
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-header-anchors
-myst_heading_anchors = 2
+myst_heading_anchors = 4
 
 
 # -- Options for myst-nb -------------------------------------------------
diff --git a/docs/source/developing_with_sdk/connecting_operators.md b/docs/source/developing_with_sdk/connecting_operators.md
diff --git a/docs/source/developing_with_sdk/core_concepts.md b/docs/source/developing_with_sdk/core_concepts.md
@@ -1 +1,3 @@
 # Core concepts
+
+This document introduces the basic concepts of the MONAI Deploy App SDK. If you are eager to try out the SDK in practice, you can start with the tutorial. After the tutorial, you can return to this document to learn more about how MONAI Deploy App SDK works.
diff --git a/docs/source/developing_with_sdk/creating_application_class.md b/docs/source/developing_with_sdk/creating_application_class.md
@@ -1 +1,3 @@
 # Creating Application class
+
+The Application class is perhaps the most important class that MONAI Deploy App developers will interact with.  A developer will inherit a new Application from the monai.core.Application base class. The base application class provides support for chaining up operators, as well as a mechanism to execute the application. The compose method of this class needs to be implemented in the inherited class to instantiate Operators and connect them together to form a Directed Acyclic Graph.
diff --git a/docs/source/developing_with_sdk/executing_docker_image_locally.md b/docs/source/developing_with_sdk/executing_docker_image_locally.md
diff --git a/docs/source/developing_with_sdk/executing_packaged_app_locally.md b/docs/source/developing_with_sdk/executing_packaged_app_locally.md
@@ -0,0 +1,101 @@
+# Executing packaged app locally
+
+The MONAI Application Runner (MAR) is a command-line utility that allows users to run and test their MONAI Application Package (MAP) locally. MAR is developed to make the running and testing of MAPs locally an easy process for developers and scientists by abstracting away the need to understand the internal details of the MAP. MAR allows the users to specify input and output paths on the local file system which it maps to the input and output of MAP during execution.
+
+## Setting up
+
+MONAI Application Runner comes as a part of the MONAI Deploy CLI and can be accessed as a `run` subcommand to the CLI. You can see the help message for MAR using the following command:
+
+```bash
+monai-deploy run --help
+```
+
+Output:
+
+```bash
+usage: monai-deploy run [-h] [-l {DEBUG,INFO,WARN,ERROR,CRITICAL}] [-q] <map-image[:tag]> <input> <output>
+
+positional arguments:
+  <map-image[:tag]>     MAP image name
+  <input>               Input data path
+  <output>              Output data directory path
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -l {DEBUG,INFO,WARN,ERROR,CRITICAL}, --log-level {DEBUG,INFO,WARN,ERROR,CRITICAL}
+                        Set the logging level (default: INFO)
+  -q, --quiet           Suppress the STDOUT and print only STDERR from the application (default: False)
+```
+
+## Syntax
+
+```bash
+monai-deploy run <container-image-name>[:tag] <input> <output> [-q|--quiet]
+```
+
+### Arguments
+
+#### Positional arguments
+
+| Name     | Format                           | Description                                                   |
+| -------- | -------------------------------- | ------------------------------------------------------------- |
+| MAP      | `container-image-name[:tag]`     | MAP container image name with or without image tag.           |
+| input    | file or directory path           | Local file or folder that contains input dataset for the MAP. |
+| output   | path                             | Local path to store output from the executing MAP.            |
+
+#### Optional arguments
+
+| Name                | Shorthand  | Default    | Description                                                       |
+| ------------------- | ---------- | ---------- | --------------------------------------------------------------    |
+| quiet               | -q         | False      | Suppress the STDOUT and print only STDERR from the application    |
+
+## Example
+
+After you have written your application using MONAI Application SDK and have packaged the application, let's try running it on your workstation using the MONAI Application Runner.
+
+### Example MAP and input
+
+Given the following information.
+
+* MAP name and tag : `monaispleen:latest`
+* Input folder  : `./spleen_input`
+* Output folder : `./spleen_output`
+
+### Launching the application
+
+```bash
+monai-deploy run monaispleen:latest spleen_input spleen_output
+```
+
+Output:
+
+```bash
+Checking dependencies...
+--> Verifying if "docker" is installed...
+
+--> Verifying if "monaispleen:latest" is available...
+
+Checking for MAP "monaispleen:latest" locally
+"monaispleen:latest" found.
+
+Reading MONAI App Package manifest...
+INFO:__main__:Operator started: 2021-09-10 21:53:25.363
+INFO:__main__:Input path: /input
+INFO:__main__:Output path: /output
+...
+...
+continued...
+```
+
+### Launching the application in quiet mode
+
+If you only want to run your application such that the STDOUT is suppressed and only STDERR from the application is printed, try using `--quiet` flag.
+
+```bash
+monai-deploy run --quiet monaispleen:latest spleen_input spleen_output
+```
+
+:::{note}
+* Currently MAR does not validate all resources specified in the MAP manifest.
+* If `gpu` is specified (>0), it executes `nvidia-docker` instead of `docker` internally to make sure that GPU is available inside the container.
+:::
diff --git a/docs/source/developing_with_sdk/index.md b/docs/source/developing_with_sdk/index.md
@@ -5,11 +5,10 @@
 :maxdepth: 2
 
 core_concepts
-creating_application_class
 creating_operator_classes
-connecting_operators
+creating_application_class
 executing_app_locally
 packaging_app
-executing_docker_image_locally
+executing_packaged_app_locally
 deploying_to_the_remote_server
 ```
diff --git a/docs/source/developing_with_sdk/packaging_app.md b/docs/source/developing_with_sdk/packaging_app.md
@@ -1 +1,77 @@
 # Packaging app
+
+In this step, the MONAI Deploy application can now be built into a deployable Docker image using the **MONAI Application Packager**.
+
+## Overview on MONAI Application Packager
+
+The MONAI Application Packager (Packager) is a utility for building an application developed with the MONAI Deploy App SDK into a structured MONAI Application Package (**MAP**).
+
+The MAP produced by the Packager is a deployable and reusable docker image that can be launched [locally](./executing_packaged_app_locally) or [remotely](./deploying_to_the_remote_server).
+
+### Basic Usage of MONAI Application Packager
+
+```bash
+monai-deploy package <APP_PATH> --tag <TAG> [--model <MODEL_PATH>] [--log-level <LEVEL>] [-h]
+```
+
+#### Required Arguments
+
+* `<APP_PATH>`: A path to MONAI Deploy Application folder or main code.
+* `--tag, -t <TAG>`: A MAP name and optionally a tag in the 'name:tag' format.
+
+::::{note}
+If `<APP_PATH>` refers to a python code (such as `./my_app.py`), only the file would be packaged into the Docker image.
+
+Please specify the application root path which includes `__main__.py` file if you want to package the whole application
+folder.
+
+The file usually would look like below:
+
+   ```python
+   # Assuming that the class `App` (that inherits Application) is defined in `app.py`.
+   from app import App
+
+   if __name__ == "__main__":
+       App(do_run=True)
+   ```
+
+::::
+
+#### Optional Arguments
+
+The following list contains arguments that have default values or are provided through the SDK if these flags are not invoked.
+However, the user can choose to override these values by invoking these optional flags:
+
+* `--model, -m <MODEL_PATH>`: A path to local directory containing all application models (will override utilizing models provided within application SDK code).
+* `--log-level, -l <LEVEL>`: A logging level (`"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, or `"CRITICAL"`).
+
+* `--base <BASE_IMAGE>`: A base docker image (overrides default `"nvcr.io/nvidia/pytorch:21.07-py3"`).
+* `--input-dir, -i <INPUT_DIR>`: A directory mounted in container for Application Input (overrides default `"input"`).
+* `--models-dir <MODELS_DIR>`: A directory mounted in container for Models Path (overrides default `"/opt/monai/models"`).
+* `--output-dir, -o <OUTPUT_DIR>`: A directory mounted in container for Application Output (overrides default `"output"`).
+* `--timeout <VALUE>`: A timeout (overrides default `0`. In seconds.).
+* `--version`: A version of the Application (overrides default `"0.0.0"`).
+* `--working-dir, -w <WORKDIR>`: A directory mounted in container for Application (overrides default `"/var/monai"`).
+* `-h, --help`: Show the help message and exit.
+
+## Example of using MONAI Application Packager
+
+Given an example MONAI Deploy App SDK application with its code residing in a directory `./spleen_segmentation_app`, packaging this application with the Packager to create a Docker image tagged `monaispleen:latest` would look like this:
+
+```bash
+$ monai-deploy package ./spleen_segmentation_app -t monaispleen:latest --model ./model.pt
+
+Building MONAI Application Package...
+Successfully built monaispleen:latest
+```
+
+The MAP image `monaispleen:latest` will be seen in the list of container images on the user's local machine when the command `docker images` is run. The MAP image `monaispleen:latest` will be able to run [locally](./executing_packaged_app_locally) or [remotely](./deploying_to_the_remote_server).
+
+```{note}
+* The current implementation (as of `0.1.0`) of the Packager **ONLY** supports [**CUDA**](https://ngc.nvidia.com/catalog/containers/nvidia:cuda) and [**Pytorch**](https://ngc.nvidia.com/catalog/containers/nvidia:pytorch) images from `nvcr.io` as base images for the MAP. There are efforts in progress to add support for smaller images from [dockerhub](https://hub.docker.com/).
+* This release was developed and tested with CUDA 11 and Python 3.8. There are efforts in progress to add support for different versions of the CUDA Toolkit.
+```
+
+## Next Step
+
+See the next page to learn more on how to locally run a MONAI application package image built by the Packager.
diff --git a/docs/source/getting_started/index.md b/docs/source/getting_started/index.md
@@ -1,7 +1,6 @@
 # GETTING STARTED
 
 ```{toctree}
-:hidden:
 :maxdepth: 2
 
 installing_app_sdk
diff --git a/docs/source/getting_started/installing_app_sdk.md b/docs/source/getting_started/installing_app_sdk.md
@@ -1 +1,15 @@
 # Installing App SDK
+
+MONAI Deploy App SDK is available as a Python package through [Python Package Index (PyPI)](https://pypi.org/project/monai-deploy-app-sdk/).
+
+MONAI Deploy App SDK's core functionality is written in Python 3 (>= 3.6) for Linux.
+
+```bash
+pip install monai-deploy-app-sdk
+```
+
+If you have installed MONAI Deploy App SDK previously, you can upgrade to the latest version with:
+
+```bash
+pip install --upgrade monai-deploy-app-sdk
+```
diff --git a/docs/source/getting_started/tutorials/01_simple_app.md b/docs/source/getting_started/tutorials/01_simple_app.md
@@ -1 +1,7 @@
 # 1) Creating a simple image processing app
+
+```{toctree}
+:maxdepth: 4
+
+../../notebooks/tutorials/01_simple_app.ipynb
+```
diff --git a/docs/source/getting_started/tutorials/02_mednist_app.md b/docs/source/getting_started/tutorials/02_mednist_app.md
@@ -1 +1,7 @@
 # 2) Creating MedNIST Classifier app
+
+```{toctree}
+:maxdepth: 4
+
+../../notebooks/tutorials/02_mednist_app.ipynb
+```
diff --git a/docs/source/introduction/index.md b/docs/source/introduction/index.md
@@ -2,7 +2,6 @@
 
 ```{toctree}
 :glob:
-:hidden:
 :maxdepth: 2
 
 overview
diff --git a/docs/source/introduction/overview.md b/docs/source/introduction/overview.md
@@ -1 +1,10 @@
 # Overview
+
+The MONAI Deploy Application SDK offers a framework and associated tools to design, verify and analyze the performance of AI-driven applications in the healthcare domain.
+It contains the following elements:
+
+- Pythonic framework for app development
+- A mechanism to package an app in a “MONAI Application Package” (MAP) instance
+- A mechanism to locally run a MAP via App Runner
+- A set of sample applications
+- API documentation
diff --git a/docs/source/release_notes/v0.1.0.md b/docs/source/release_notes/v0.1.0.md
@@ -1,4 +1,4 @@
-# Version 0.1.0 (September 12, 2021)
+# Version 0.1.0 (September 20, 2021)
 
 ## What's new?
 
diff --git a/examples/apps/simple_imaging_app/gaussian_operator.py b/examples/apps/simple_imaging_app/gaussian_operator.py
diff --git a/examples/apps/simple_imaging_app/sobel_operator.py b/examples/apps/simple_imaging_app/sobel_operator.py
diff --git a/monai/deploy/core/domain/datapath.py b/monai/deploy/core/domain/datapath.py
diff --git a/monai/deploy/core/operator.py b/monai/deploy/core/operator.py
diff --git a/notebooks/tutorials/01_simple_app.ipynb b/notebooks/tutorials/01_simple_app.ipynb
diff --git a/notebooks/tutorials/02_mednist_app.ipynb b/notebooks/tutorials/02_mednist_app.ipynb

Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
`1`	`1`	`# Core concepts`
	`2`	`+`
	`3`	`+This document introduces the basic concepts of the MONAI Deploy App SDK. If you are eager to try out the SDK in practice, you can start with the tutorial. After the tutorial, you can return to this document to learn more about how MONAI Deploy App SDK works.`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
`1`	`1`	`# Creating Application class`
	`2`	`+`
	`3`	`+The Application class is perhaps the most important class that MONAI Deploy App developers will interact with. A developer will inherit a new Application from the monai.core.Application base class. The base application class provides support for chaining up operators, as well as a mechanism to execute the application. The compose method of this class needs to be implemented in the inherited class to instantiate Operators and connect them together to form a Directed Acyclic Graph.`