SDK 2.0.0 Docs review (fixes #100)

docs/docs/.pages

@@ -2,7 +2,7 @@ arrange:
   - index.md
   - Getting_Started.md
   - Building_Your_First_Plugin
+  - Versioning_And_Upgrade
   - References
-  - Versioning_And_Upgrading
   - Best_Practices
   - Release_Notes

docs/docs/Best_Practices/.pages

@@ -6,4 +6,3 @@ arrange:
   - Sensitive_Data.md
   - Unicode_Data.md
   - Working_with_Powershell.md
-  - Replication

docs/docs/Building_Your_First_Plugin/Data_Ingestion.md

@@ -1,7 +1,3 @@
----
-title: Virtualization SDK
----
-
 # Data Ingestion
 
 ## How Does Delphix Ingest Data?
@@ -293,4 +289,4 @@ screen you see should ask for the properties that you recently added to your `li
 After you have finished entering this information, the initial sync process will begin. This is what will call your pre-snapshot operation, thus copying data.
 
 !!! warning "Gotcha"
-    Manually creating a dSource sets your plugin’s linked source schema in stone, and you will have to recreate the dSource in order to modify your schema. We will cover how to deal with this correctly later, in the upgrade section. For now, if you need to change your plugin's linked source schema, you will have to first delete any dSources you have manually added.
+    Manually creating a dSource sets your plugin’s linked source schema in stone, and you will have to recreate the dSource in order to modify your schema. We will cover how to deal with this correctly later, in the [upgrade section](/Versioning_And_Upgrade/Upgrade.md). For now, if you need to change your plugin's linked source schema, you will have to first delete any dSources you have manually added.

docs/docs/Building_Your_First_Plugin/Discovery.md

@@ -1,7 +1,3 @@
----
-title: Virtualization SDK
----
-
 # Discovery
 
 ## What is Discovery?
@@ -250,7 +246,7 @@ Once you have added one or more source configs, you will be able to sync. This i
 
 
 !!! warning
-    Once you have automatically or manually created source configs, you will not be allowed to modify your plugin's source config schema. We will cover how to deal with this later in the upgrade section. For now, if you need to change your plugin's source config schema:
+    Once you have automatically or manually created source configs, you will not be allowed to modify your plugin's source config schema. We will cover how to deal with this later in the [upgrade section](/Versioning_And_Upgrade/Upgrade.md). For now, if you need to change your plugin's source config schema:
 
     - You will have to delete any source configs you have manually added.
-    - Delete the plugin and its corresponding objects (dSources, Virtual Sources, etc) if the source configs were manually discovered.
+    - Delete the plugin and its corresponding objects (dSources, Virtual Sources, etc) if the source configs were manually discovered.

docs/docs/Building_Your_First_Plugin/Overview.md

@@ -1,8 +1,3 @@
----
-title: Virtualization SDK
----
-
-
 # Overview
 
 In the following few pages, we will walk through an example of making a simple, working plugin.
@@ -59,6 +54,6 @@ Defining your plugin’s schemas will enable it to give the Delphix Engine the d
 To complete the tutorial that follows, make sure you check off the things on this list:
 
 - Download the SDK and get it working
-- A running Delphix Engine, version x.y.z or above.
-- Add at least one Unix host—but preferably three—to the Delphix Engine as remote environments
+- A running Delphix Engine version 6.0.2.0 or above.
+- Add at least one Unix host—but preferably three—to the Delphix Engine as remote environments.
 - Have a tool at hand for editing text files—mostly Python and JSON. A simple text editor would work fine, or you can use a full-fledged IDE.

docs/docs/Building_Your_First_Plugin/Provisioning.md

@@ -1,7 +1,3 @@
----
-title: Virtualization SDK
----
-
 # Provisioning
 
 ## What is Provisioning?

docs/docs/Getting_Started.md

@@ -14,7 +14,7 @@ The platform and libs modules expose objects and methods needed to develop a plu
 - macOS 10.14+, Ubuntu 16.04+, or Windows 10
 - Python 2.7 (Python 3 is not supported)
 - Java 7+
-- Delphix Engine 5.3.5.0 or above
+- Delphix Engine 6.0.2.0 or above
 
 ## Installation
 To install the latest version of the SDK run:
@@ -63,4 +63,8 @@ $ dvp upload -e <delphix_engine_address> -u <delphix_admin_user> -a <artifact_fi
 
 You will be prompted for the Delphix Engine user's password.
 
-You can also use a [CLI Configuration File](/Best_Practices/CLI_Configuration_File.md) to set default values for [CLI](/References/CLI.md) command options.
+You can also use a [CLI Configuration File](/Best_Practices/CLI_Configuration_File.md) to set default values for [CLI](/References/CLI.md) command options.
+
+## Questions?
+
+If you have questions, bugs or feature requests reach out to us via the [Virtualization SDK GitHub repository](https://github.com/delphix/virtualization-sdk/).

docs/docs/References/CLI.md

@@ -5,7 +5,7 @@ The CLI is installed with the SDK. To install the SDK, refer to the [Getting Sta
 ## Help
 Every command has a `-h` flag including the CLI itself. This will print the help menu.
 
-####Examples
+#### Examples
 Get the CLI's help menu.
 
 ```
@@ -19,14 +19,18 @@ Options:
   --version      Show the version and exit.
   -v, --verbose  Enable verbose mode. Can be repeated up to three times for
                  increased verbosity.
+
   -q, --quiet    Enable quiet mode. Can be repeated up to three times for
                  increased suppression.
+
   -h, --help     Show this message and exit.
 
 Commands:
-  build   Build the plugin code and generate upload artifact file using the...
-  init    Create a plugin in the root directory.
-  upload  Upload the generated upload artifact (the plugin JSON file) that...
+  build          Build the plugin code and generate upload artifact file...
+  download-logs  Download plugin logs from a target Delphix Engine to a...
+  init           Create a plugin in the root directory.
+  upload         Upload the generated upload artifact (the plugin JSON
+                 file)...
 ```
 
 
@@ -76,7 +80,7 @@ $ dvp -vvv build
 Print nothing to the console.
 
 ```
-$ dvp -qqq upload -e engine.example.com -u admin
+$ dvp -qqq build
 ```
 
 ## Commands
@@ -91,6 +95,7 @@ Create a plugin in the root directory. The plugin will be valid but have no func
 |-r,<br>--root-dir<br>DIRECTORY|Set the plugin root directory.|N|`os.cwd()`|
 |-n,<br>--plugin-name<br>TEXT|Set the name of the plugin that will be used to identify it.|N|id|
 |-s,<br>--ingestion-strategy<br>[DIRECT\|STAGED]|Set the ingestion strategy of the plugin. A "direct" plugin ingests without a staging server while a "staged" plugin requires a staging server.|N|`DIRECT`|
+|-t,<br>--host-type<br>[UNIX\|WINDOWS]|Set the host platform supported by the plugin.|N|`UNIX`|
 
 
 #### Examples
@@ -115,7 +120,7 @@ $ dvp init -n mongodb -s STAGED -r /our/plugin/directory
 Create a `WINDOWS` plugin called `mssql` in the current working directory with the `DIRECT` ingestion strategy.
 
 ```
-$ dvp init -n mssql -p WINDOWS
+$ dvp init -n mssql -t WINDOWS
 ```
 
 ***
@@ -161,13 +166,14 @@ Upload the generated upload artifact (the plugin JSON file) that was built to a
 |Option &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|Description|Required|Default &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|
 |-------|-----------|:--------:|:-------:|
 |-e,<br>--delphix-engine<br>TEXT|Upload plugin to the provided engine. This should be either the hostname or IP address.|Y|None|
-|-u,<br>--user<br>TEXT|Authenticate to the Delphix Engine with the provided user.|Y| None |
+|-u,<br>--user<br>TEXT|Authenticate to the Delphix Engine with the provided user.|Y|None|
 |-a,<br>--upload-artifact FILE|Path to the upload artifact that was generated through build.|N|`artifact.json`|
-|--password<br>TEXT|Authenticate using the provided password. If ommitted, the password will be requested through a secure prompt.|N| None |
+|--wait|Block and wait for the upload job to finish on the Delphix Engine.|N|None|
+|--password<br>TEXT|Authenticate using the provided password. If ommitted, the password will be requested through a secure prompt.|N|None|
 
 
 #### Examples
-Upload artifact `build/artifact.json` to `delphix-engine.domain` using the user `admin`. Since the password option is ommitted, a secure password prompt is used instead.
+Upload artifact `build/artifact.json` to `engine.example.com` using the user `admin`. Since the password option is ommitted, a secure password prompt is used instead.
 
 ```
 $ dvp upload -a build/artifact -e engine.example.com -u admin

docs/docs/References/Classes.md

@@ -1,7 +1,3 @@
----
-title: Virtualization SDK
----
-
 # Classes
 
 ## DirectSource

docs/docs/References/Decorators.md

@@ -1,7 +1,3 @@
----
-title: Virtualization SDK
----
-
 # Decorators
 
 The Virtualization SDK exposes decorators to be able to annotate functions that correspond to each [Plugin Operation](Plugin_Operations.md).

docs/docs/References/Glossary.md

@@ -11,10 +11,10 @@ A single file that is the result of a [build](#building). It is this artifact wh
 The process of creating an [artifact](#artifact) from the collection of files that make up the plugin's source code.
 
 ## Data Migration
-A python function which is called as part of the upgrade process. It handles transforming data from an older format to a newer format. More details [here](/Versioning_And_Upgrading/Upgrading.md#data-migrations).
+A python function which is called as part of the upgrade process. It handles transforming data from an older format to a newer format. More details [here](/Versioning_And_Upgrade/Upgrade.md#data-migrations).
 
 ## Data Migration ID
-Each data migration is tagged with a unique ID. This allows the Delphix Engine to know which data migrations need to be run, in which order, when upgrading to a new plugin version. More details [here](/Versioning_And_Upgrading/Upgrading.md#data-migrations).
+Each data migration is tagged with a unique ID. This allows the Delphix Engine to know which data migrations need to be run, in which order, when upgrading to a new plugin version. More details [here](/Versioning_And_Upgrade/Upgrade.md#data-migrations).
 
 ## Decorator
 A Python construct which is used by plugins to "tag" certain functions, so that the Delphix Engine knows which function corresponds to which plugin operation.
@@ -72,7 +72,7 @@ For example, a MySQL plugin might provide an operation called "stop" which knows
 The process of making a virtual copy of a dataset and making it available for use on a target environment.
 
 ## Replication
-Delphix allows engine user to replicate data objects between Delphix Engines by creating a replication spec. Data objects that belong to a plugin can also be part of the replication spec. More details [here](/Best_Practices/Replication/Replication.md).
+Delphix allows end users to replicate data objects between Delphix Engines by creating a replication profile. Data objects that belong to a plugin can also be part of the replication profile. Refer to the [Delphix Engine Documentation](https://docs.delphix.com/docs/) for more details.
 
 ## Repository
 Information that represents a set of dependencies that a dataset requires in order to be functional. For example, a particular Postgres database might require an installed Postgres 9.6 DBMS, and so its associated repository would contain all the information required to interact with that DBMS.

docs/docs/References/Platform_Libraries.md

@@ -1,7 +1,3 @@
----
-title: Virtualization SDK
----
-
 # Platform Libraries
 Set of functions that plugins can use these for executing remote commands, etc.
 

docs/docs/References/Plugin_Config.md

@@ -9,8 +9,8 @@ The name of the file can be specified during the build. By default, the build lo
 |----------|:------:|:--:|-----------|
 |id|Y|string|The unique id of the plugin in a valid UUID format.|
 |name|N|string|The display name of the plugin. This will be used in the UI. If it is not specified name will be equal to id.|
-|externalVersion|N|string|The plugin's [external version](/Versioning_And_Upgrading/Versioning.md#external-version). This is a freeform string. If it is not supplied, the build number is used as an external version.
-|buildNumber|Y|string|The plugin's [build number](/Versioning_And_Upgrading/Versioning.md#build-number). This string must conform to the format described [here](/Versioning_And_Upgrading/Versioning.md#build-number-format-rules).
+|externalVersion|N|string|The plugin's [external version](/Versioning_And_Upgrade/Versioning.md#external-version). This is a freeform string. If it is not supplied, the build number is used as an external version.
+|buildNumber|Y|string|The plugin's [build number](/Versioning_And_Upgrade/Versioning.md#build-number). This string must conform to the format described [here](/Versioning_And_Upgrade/Versioning.md#build-number-format-rules).
 |hostTypes|Y|list|The host type that the plugin supports. Either `UNIX` or `WINDOWS`.|
 |schemaFile|Y|string|The path to the JSON file that contains the [plugin's schema definitions](Schemas.md).<br><br>This path can be absolute or relative to the directory containing the plugin config file.|
 |srcDir|Y|string|The path to the directory that contains the source code for the plugin. During execution of a plugin operation, this directory will be the current working directory of the Python interpreter. Any modules or resources defined outside of this directory will be inaccessible at runtime.<br><br>This path can be absolute or relative to the directory containing the plugin config file.|
@@ -53,13 +53,13 @@ srcDir: src/
 schemaFile: schema.json
 pluginType: DIRECT
 language: PYTHON27
+buildNumber: 0.1.0
 ```
-This is a valid plugin config for the plugin with manualDiscovery set to false:
+This is a valid plugin config for the plugin with `manualDiscovery` set to `false` and an `externalVersion` set:
 
 ```yaml
 id: 7cf830f2-82f3-4d5d-a63c-7bbe50c22b32
 name: MongoDB
-version: 2.0.0
 hostTypes:
   - UNIX
 entryPoint: mongo_runner:mongodb
@@ -68,4 +68,6 @@ schemaFile: schema.json
 manualDiscovery: false
 pluginType: DIRECT
 language: PYTHON27
+externalVersion: "MongoDB 1.0"
+buildNumber: "1"
 ```