Populate initial user guide docs

docs/_static/custom.css

@@ -7,27 +7,101 @@ https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/customizing.html
 body {
     font-family: "Roboto", sans-serif;
 }
+
 .wy-menu-vertical p.caption {
     color: #7cccc7;
 }
+
 * {
     font-variant-ligatures: none;
 }
+
 .autoclasstoc td {
     padding: 0.2rem;
     line-height: normal;
 }
-dl.field-list > dt {
+
+dl.field-list>dt {
     word-break: normal;
 }
 
-
-
 h5.card-header {
     margin-top: 0px;
     margin-bottom: 0px;
 }
+
 h5.card-header::before {
     height: 0px;
     margin-top: 0px;
 }
+
+
+/* Customize styles */
+
+:root {
+    --pst-color-inline-code: 232, 62, 140;
+    --pst-font-size-h1: 32px;
+    --pst-font-size-h2: 26px;
+    --pst-font-size-h3: 21px;
+    --pst-font-size-h4: 18px;
+    --pst-font-size-h5: 16px;
+    --pst-font-size-h6: 14px;
+}
+
+
+/* Customize headings */
+
+.heading-style,
+h1 {
+    font-family: Content-font, Roboto, sans-serif;
+    font-weight: 500;
+    line-height: 1.5;
+}
+
+/* Code Highlight */
+div[class^="highlight"] pre {
+    color: rgb(248, 248, 242);
+    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(127, 218, 255)
+}
+
+/* Code highlight in source code view */
+.viewcode-block:target {
+    background-color: #382927;
+}
+
+/* Backquote */
+blockquote {
+    background-color: rgb(129 252 255 / 30%);
+    border-left: 8px solid rgb(127, 218, 255);
+    padding: 15px 30px 15px 15px;
+}
+blockquote p {
+    margin-bottom: 0px;
+}

docs/requirements.txt

@@ -30,3 +30,4 @@ sphinxcontrib-htmlhelp
 sphinxcontrib-jsmath
 sphinxcontrib-qthelp
 sphinxcontrib-serializinghtml
+sphinxcontrib-mermaid

docs/source/_templates/navbar-logo.html

@@ -10,8 +10,8 @@
     <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
   </a>
   <a href="{{ pathto(master_doc) }}">
-    <p style="z-index:100; position:absolute; font-size:16px; font-weight:bold; left:5px; top:45px; margin-bottom:0;">
-      Deploy Application SDK
+    <p style="z-index:100; position:absolute; font-size:16px; font-weight:bold; left:12px; top:45px; margin-bottom:0;">
+      Deploy App SDK
     </p>
   </a>
 </div>
@@ -22,6 +22,6 @@
 {% endif %}
 {% else %}
 <a class="navbar-brand" href="{{ pathto(master_doc) }}">
-<p class="title">{{ project }}</p>
+  <p class="title">{{ project }}</p>
 </a>
-{% endif %}
+{% endif %}

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>

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
@@ -140,7 +144,7 @@
     "index": ["search-field", "sidebar-quicklinks", "sidebar-nav-bs"],
     "**": ["search-field", "sidebar-nav-bs"],
 }
-pygments_style = "sphinx"
+pygments_style = "monokai"
 
 
 # -- Options for pydata-sphinx-theme -------------------------------------------------
@@ -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 -------------------------------------------------

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.

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.

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.
+:::

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
 ```