ODSC-42082: Add usage of the ads opctl init to the ADS docs (#166)

Author: mrDzurb

docs/Makefile

@@ -0,0 +1,32 @@
+# 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
+ZIP_TARGET    = ads-latest.zip
+
+# 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)
+	@rm -rf dask-worker-space
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+zip: html
+	@cd build/html && zip -r ../../"$(ZIP_TARGET)" .
+	@echo "built: $(ZIP_TARGET)"
+
+clean:
+	rm -rf $(BUILDDIR)/*

docs/source/conf.py

@@ -32,7 +32,11 @@
     "sphinx.ext.inheritance_diagram",
     "nbsphinx",
     "sphinx_code_tabs",
-    "sphinx_copybutton"
+    "sphinx_copybutton",
+    "sphinx.ext.duration",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/user_guide/cli/opctl/configure.rst

@@ -1,9 +1,12 @@
+#################
 CLI Configuration
-=================
+#################
 
-**Prerequisite**
+.. _configuration_prerequisites:
 
-* You have completed :doc:`ADS CLI installation <../quickstart>`
+.. admonition:: Prerequisites
+
+    - You have completed :doc:`ADS CLI installation <../quickstart>`
 
 
 Setup default values for different options while running ``OCI Data Sciecne Jobs`` or ``OCI DataFlow``. By setting defaults, you can avoid inputing compartment ocid, project ocid, etc.
@@ -40,14 +43,14 @@ This will prompt you to setup default ADS CLI configurations for each OCI profil
     subnet_id = oci.xxxx.<subnet-ocid>
     log_group_id = oci.xxxx.<log_group_ocid>
     log_id = oci.xxxx.<log_ocid>
-    shape_name = VM.Standard2.2
+    shape_name = VM.Standard.E2.4
     block_storage_size_in_GBs = 100
 
     [ANOTHERPROF]
     compartment_id = oci.xxxx.<compartment_ocid>
     project_id = oci.xxxx.<project_ocid>
     subnet_id = oci.xxxx.<subnet-ocid>
-    shape_name = VM.Standard2.1
+    shape_name = VM.Standard.E2.4
     log_group_id =ocid1.loggroup.oc1.xxx.xxxxx
     log_id = oci.xxxx.<log_ocid>
     block_storage_size_in_GBs = 50
@@ -57,10 +60,10 @@ This will prompt you to setup default ADS CLI configurations for each OCI profil
 
 .. code-block::
 
-    [MYTENANCYPROF]
+    [DEFAULT]
     compartment_id = oci.xxxx.<compartment_ocid>
-    driver_shape = VM.Standard2.1
-    executor_shape = VM.Standard2.1
+    driver_shape = VM.Standard.E2.4
+    executor_shape = VM.Standard.E2.4
     logs_bucket_uri = oci://mybucket@mytenancy/dataflow/logs
     script_bucket = oci://mybucket@mytenancy/dataflow/mycode/
     num_executors = 3
@@ -79,6 +82,34 @@ This will prompt you to setup default ADS CLI configurations for each OCI profil
     compartment_id = oci.xxxx.<compartment_ocid>
     project_id = oci.xxxx.<project_ocid>
 
+``~/.ads_ops/model_deployment_config.ini`` will contain defaults for deploying ``Data Science Model``. Defaults are set for each profile listed in your oci config file. Here is a sample -
+
+.. code-block::
+
+    [DEFAULT]
+    compartment_id = ocid1.compartment.oc1..<unique_ID>
+    project_id = ocid1.datascienceproject.oc1.iad.<unique_ID>
+    shape_name = VM.Standard.E2.4
+    log_group_id = ocid1.loggroup.oc1.iad.<unique_ID>
+    log_id = ocid1.log.oc1.iad.<unique_ID>
+    compartment_id = oci.xxxx.<compartment_ocid>
+    project_id = oci.xxxx.<project_ocid>
+    bandwidth_mbps = 10
+    replica = 1
+    web_concurrency = 10
+
+    [ANOTHERPROF]
+    compartment_id = ocid1.compartment.oc1..<unique_ID>
+    project_id = ocid1.datascienceproject.oc1.iad.<unique_ID>
+    shape_name = VM.Standard.E2.4
+    log_group_id = ocid1.loggroup.oc1.iad.<unique_ID>
+    log_id = ocid1.log.oc1.iad.<unique_ID>
+    compartment_id = oci.xxxx.<compartment_ocid>
+    project_id = oci.xxxx.<project_ocid>
+    bandwidth_mbps = 20
+    replica = 2
+    web_concurrency = 20
+
 
 ``~/.ads_ops/local_backend.ini`` will contain defaults for running jobs and pipeline steps locally. While local operations do not involve connections to OCI services, default
 configurations are still set for each profile listed in your oci config file for consistency. Here is a sample -
@@ -93,3 +124,46 @@ configurations are still set for each profile listed in your oci config file for
     [ANOTHERPROF]
     max_parallel_containers = 4
     pipeline_status_poll_interval_seconds = 5
+
+
+Generate Starter YAML
+---------------------
+
+The examples demonstrated in this section show how to generate starter YAML specification for the Data Science Job, Data Flow Application, Data Science Model Deployment and ML Pipeline services. It takes into account the config files generated within ``ads opctl configure`` operation, as well as values extracted from the environment variables.
+
+To generate starter specification run -
+
+.. code-block::
+
+    ads opctl init --help
+
+The resource type is a mandatory attribute that needs to be provided. Currently supported resource types -  `dataflow`, `deployment`, `job` and `pipeline`.
+For instance to generate starter specification for the Data Science job, run -
+
+.. code-block::
+
+    ads opctl init job
+
+The resulting YAML will be printed in the console. By default the ``python`` runtime will be used.
+
+
+**Supported runtimes**
+
+ - For a ``job`` - `container`, `gitPython`, `notebook`, `python` and `script`.
+ - For a ``pipeline`` - `container`, `gitPython`, `notebook`, `python` and `script`.
+ - For a ``dataflow`` - `dataFlow` and `dataFlowNotebook`.
+ - For a ``deployment`` - `conda` and `container`.
+
+
+If you want to specify a particular runtime use -
+
+.. code-block::
+
+    ads opctl init job --runtime-type container
+
+Use the ``--output`` attribute to save the result in a YAML file.
+
+.. code-block::
+
+    ads opctl init job --runtime-type container --output job_with_container_runtime.yaml
+