From a8453cc87dda1335e9b8c68b1668476486cf69fa Mon Sep 17 00:00:00 2001
From: andf-viam <132301587+andf-viam@users.noreply.github.com>
Date: Thu, 19 Oct 2023 13:59:14 -0400
Subject: [PATCH] DOCS-1275: Add CLI module upload file, dir (#2052)

---
 docs/manage/CLI.md                      |  12 +-
 docs/modular-resources/upload/_index.md | 162 +++++++++++++-----------
 2 files changed, 92 insertions(+), 82 deletions(-)

diff --git a/docs/manage/CLI.md b/docs/manage/CLI.md
index 92cfd22fc2..f33c5b5746 100644
--- a/docs/manage/CLI.md
+++ b/docs/manage/CLI.md
@@ -356,7 +356,7 @@ This includes:
 ```sh {class="command-line" data-prompt="$"}
 viam module create --name <module-id> [--org-id <org-id> | --public-namespace <namespace>]
 viam module update [--org-id <org-id> | --public-namespace <namespace>] [--module <path to meta.json>]
-viam module upload --version <version> --platform <platform> [--org-id <org-id> | --public-namespace <namespace>] [--module <path to meta.json>] <packaged-module.tar.gz>
+viam module upload --version <version> --platform <platform> [--org-id <org-id> | --public-namespace <namespace>] [--module <path to meta.json>] <module-path>
 ```
 
 Examples:
@@ -387,7 +387,7 @@ If you update and release your module as part of a continuous integration (CI) w
 | ----------- | ----------- | ----------- |
 | `create`    | generate new metadata for a custom module on your local filesystem  | - |
 | `update`    | update an existing custom module on your local filesystem with recent changes to the [`meta.json` file](#the-metajson-file) | - |
-| `upload`    | validate and upload a new or existing custom module on your local filesystem to the Viam registry. See [Upload validation](#upload-validation) for more information |
+| `upload`    | validate and upload a new or existing custom module on your local filesystem to the Viam registry. See [Upload validation](#upload-validation) for more information | **module-path** : specify the path to the file, directory, or compressed archive (with `.tar.gz` or `.tgz` extension) that contains your custom module code |
 | `--help`      | return help      | - |
 
 ##### Named arguments
@@ -440,13 +440,13 @@ Therefore, you are able to change the `entrypoint` file from version to version,
 
 ##### Upload validation
 
-When you `upload` a module, the command validates your local packaged module to ensure that it meets the requirements to successfully upload to the Viam registry.
+When you `upload` a module, the command performs basic validation of your module to check for common errors.
 The following criteria are checked for every `upload`:
 
-- The packaged module must exist on the filesystem at the path provided to the `upload` command.
-- The packaged module must use the `.tar.gz` or `.tgz` extension.
+- The module must exist on the filesystem at the path provided to the `upload` command.
 - The entry point file specified in the [`meta.json` file](#the-metajson-file) must exist on the filesystem at the path specified.
 - The entry point file must be executable.
+- If the module is provided to the `upload` command as a compressed archive, the archive must have the `.tar.gz` or `.tgz` extension.
 
 ##### The `meta.json` file
 
@@ -498,7 +498,7 @@ The `meta.json` file includes the following configuration options:
     <td><code>entrypoint</code></td>
     <td>string</td>
     <td><strong>Required</strong></td>
-    <td>The name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program.</td>
+    <td>The name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program. If you are providing your module as a single file to the <code>upload</code> command, provide the path to that single file. If you are providing a directory containing your module to the <code>upload</code> command, provide the path to the entry point file contained within that directory.</td>
   </tr>
 </table>
 
diff --git a/docs/modular-resources/upload/_index.md b/docs/modular-resources/upload/_index.md
index da03d609c4..e81398b780 100644
--- a/docs/modular-resources/upload/_index.md
+++ b/docs/modular-resources/upload/_index.md
@@ -30,9 +30,9 @@ To upload your custom module to the [Viam registry](https://app.viam.com/registr
 
 1. First, [install the Viam CLI](/manage/cli/#install) and [authenticate](/manage/cli/#authenticate) to Viam, from the same machine that you intend to upload your module from.
 
-2. Next, run the `viam module create` command to select a new custom module name and generate module metadata.
-   By default, a module is created as private.
-   Run this command according to your desired visibility for your module:
+2. Next, run the `viam module create` command to select a new custom module name and generate the required metadata for your module.
+   By default, a new module is created as _private_, meaning that it is only accessible to members of your [organization](/manage/fleet/organizations/), but you can choose to set your module as _public_ to make it accessible to all Viam users.
+   Follow the instructions below according to whether you want to upload a public or private module:
 
 {{< tabs >}}
 {{% tab name="Private" %}}
@@ -43,9 +43,17 @@ Get the `org-id` for your {{< glossary_tooltip term_id="organization" text="orga
 viam module create --name <your-module-name> --org-id <your-org-id>
 ```
 
+This command creates a new `meta.json` metadata file in your current working directory, which serves as a template.
+
+If you later wish to make your module public, you can use the `viam module update` command to do so.
+
 {{% /tab %}}
 {{% tab name="Public" %}}
 
+{{% alert title="Important" color="note" %}}
+Once you update your module to mark it as public, you cannot change it back to private.
+{{% /alert %}}
+
 1. If you haven't already, [create a new namespace](/manage/fleet/organizations/#create-a-namespace-for-your-organization) for your organization.
    If you have already created a namespace, you can find it on your organization's **Settings** page in [the Viam App](https://app.viam.com/), or by running the [`viam organizations list`](/manage/cli/#organizations) command.
 
@@ -55,15 +63,19 @@ viam module create --name <your-module-name> --org-id <your-org-id>
 viam module create --name <your-module-name> --public-namespace <your-unique-namespace>
 ```
 
+This command creates a new `meta.json` metadata file in your current working directory, which serves as a template.
+
 {{% /tab %}}
 {{< /tabs >}}
 
-This command creates a new `meta.json` metadata file in your current working directory, which serves as a template.
-Edit and then upload the `meta.json` file to set important configuration information about your module, such as whether it will be publicly available to all Viam users or only available within your organization.
-
 3. Edit the newly-created `meta.json` file, and provide the required configuration information for your custom module by filling in the following fields.
    The `name` field is pre-populated using the `--name` you provided in the `viam module create` command, and `visibility` is set to `private` by default.
 
+   {{< alert title="Caution" color="caution" >}}
+   The `module_id` uniquely identifies your module.
+   Do not change the `module_id`.
+   {{< /alert >}}
+
    <table class="table table-striped">
      <tr>
        <th>Name</th>
@@ -106,35 +118,36 @@ Edit and then upload the `meta.json` file to set important configuration informa
        <td><code>entrypoint</code></td>
        <td>string</td>
        <td><strong>Required</strong></td>
-       <td>The name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program.</td>
+       <td>The name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program. If you are providing your module as a single file to the <code>upload</code> command, provide the path to that single file. If you are providing a directory containing your module to the <code>upload</code> command, provide the path to the entry point file contained within that directory.</td>
      </tr>
+
    </table>
 
-   For example, the following represents the configuration of an example `my-module` public module in the `acme` namespace:
-
-   ```json {class="line-numbers linkable-line-numbers"}
-   {
-     "module_id": "acme:my-module",
-     "visibility": "public",
-     "url": "https://github.com/acme-co-example/my-module",
-     "description": "An example custom module.",
-     "models": [
-       {
-         "api": "rdk:component:generic",
-         "model": "acme:demo:my-model"
-       }
-     ],
-     "entrypoint": "my-module.sh"
-   }
-   ```
+For example, the following represents the configuration of an example `my-module` public module in the `acme` namespace:
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+  "module_id": "acme:my-module",
+  "visibility": "public",
+  "url": "https://github.com/acme-co-example/my-module",
+  "description": "An example custom module.",
+  "models": [
+    {
+      "api": "rdk:component:generic",
+      "model": "acme:demo:my-model"
+    }
+  ],
+  "entrypoint": "my-module.sh"
+}
+```
 
-   {{% alert title="Important" color="note" %}}
-   If you are publishing a public module (`"visibility": "public"`), the [namespace of your model](/modular-resources/key-concepts/#naming-your-model) must match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization).
-   In the example above, the model namespace is set to `acme` to match the owning organization's namespace.
-   If the two namespaces do not match, the command will return an error.
-   {{% /alert %}}
+{{% alert title="Important" color="note" %}}
+If you are publishing a public module (`"visibility": "public"`), the [namespace of your model](/modular-resources/key-concepts/#naming-your-model) must match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization).
+In the example above, the model namespace is set to `acme` to match the owning organization's namespace.
+If the two namespaces do not match, the command will return an error.
+{{% /alert %}}
 
-   See [The `meta.json` file](/manage/cli/#the-metajson-file) for more information.
+See [The `meta.json` file](/manage/cli/#the-metajson-file) for more information.
 
 4. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam registry.
    Run this command from within the same directory as your `meta.json` file:
@@ -145,31 +158,23 @@ Edit and then upload the `meta.json` file to set important configuration informa
 
    On a successful update, the command will return a link to the updated module in the Viam registry.
 
-5. Package your custom module to get it ready to upload to the Viam registry.
-   Currently, the Registry only supports `tar.gz` or `tar.xz` format.
-   Use the command below specific for the language of your module:
-
-   - To package a module written in Go, run the following commands from the same directory as your `meta.json` file:
-
-     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
-     go build -o bin/module ./module/main.go
-     tar -czf module.tar.gz bin/module
-     ```
+5. (Python only) For modules written in Python, you likely want to package your module files as an archive first, before uploading.
+   Other languages can proceed to the next step to upload their module directly.
+   To package a module written in Python, run the following command from the same directory as your `meta.json` file:
 
-     For more information, see [Compile a module into an executable](/modular-resources/create/#compile-the-module-into-an-executable).
-
-   - To package a module written in Python, run the following command from the same directory as your `meta.json` file:
+   ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+   tar -czf module.tar.gz run.sh requirements.txt src
+   ```
 
-     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
-     tar -czf module.tar.gz run.sh requirements.txt src
-     ```
+   Where `run.sh` is your [entrypoint file](/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module.
 
-     Where `run.sh` is your [entrypoint file](/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module.
+   Supply the path to the resulting archive file in the next step.
 
-6. Run `viam module upload` to upload the updated custom module to the Viam registry:
+6. Run `viam module upload` to upload your custom module to the Viam registry.
+   Specify the path to the file, directory, or compressed archive (with `.tar.gz` or `.tgz` extension) that contains your custom module code:
 
    ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
-   viam module upload --version <version> --platform <platform> module.tar.gz
+   viam module upload --version <version> --platform <platform> <module-path>
    ```
 
    Where:
@@ -182,7 +187,7 @@ Edit and then upload the `meta.json` file to set important configuration informa
      - `darwin/amd64` - macOS computers running the Intel `x86_64` architecture.
      - `linux/arm64` - Linux computers or {{< glossary_tooltip term_id="board" text="boards" >}} running the `arm64` (`aarch64`) architecture, such as the Raspberry Pi.
      - `linux/amd64` - Linux computers or {{< glossary_tooltip term_id="board" text="boards" >}} running the Intel `x86_64` architecture.
-   - `path` - provide the path to the compressed archive, in `tar.gz` or `tar.xz` format, that contains your custom module code.
+   - `module-path` - provide the path to the file, directory, or compressed archive (with `.tar.gz` or `.tgz` extension) that contains your custom module code.
 
    {{% alert title="Important" color="note" %}}
    The `viam module upload` command only supports one `platform` argument at a time.
@@ -191,13 +196,27 @@ Edit and then upload the `meta.json` file to set important configuration informa
    The Viam registry page for your module displays the platforms your module supports for each version you have uploaded.
    {{% /alert %}}
 
-   For example, the following command uploads the compressed `module.tar.gz` archive to the Viam registry when run in the same directory as the corresponding `meta.json` file:
+   For example:
 
-   ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
-   viam module upload --version 1.0.0 --platform darwin/arm64 module.tar.gz
-   ```
+   - To upload a custom module that is defined in a single file named `my-module-file`, written to a local `bin` directory:
+
+     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+     viam module upload --version 1.0.0 --platform linux/amd64 ./bin/my-module-file
+     ```
+
+   - To upload a custom module that includes multiple files, as well as a separate entry point file, all contained with a local `bin` directory:
+
+     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+     viam module upload --version 1.0.0 --platform linux/amd64 ./bin
+     ```
+
+   - To upload a custom module that has been compressed as an archive named `packaged-module.tar.gz`:
+
+     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+     viam module upload --version 1.0.0 --platform linux/amd64 packaged-module.tar.gz
+     ```
 
-   When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam registry.
+   When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your module to check for common errors.
 
 For more information, see the [`viam module` command](/manage/cli/#module)
 
@@ -229,40 +248,31 @@ To update an existing module in the [Viam registry](https://app.viam.com/registr
 
    On a successful update, the command will return a link to the updated module in the Viam registry.
 
-1. Package your custom module to get it ready to upload to the Viam registry.
-   Currently, the Registry only supports `tar.gz` or `tar.xz` format.
-   Use the command below specific for the language of your module:
-
-   - To package a module written in Go, run the following commands from the same directory as your `meta.json` file:
-
-     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
-     go build -o bin/module ./module/main.go
-     tar -cxf module.tar.gz bin/module
-     ```
+1. (Python only) For modules written in Python, you likely want to package your module files as an archive first, before uploading.
+   Other languages can proceed to the next step to upload their module directly.
+   To package a module written in Python, run the following command from the same directory as your `meta.json` file:
 
-     For more information, see [Compile a module into an executable](/modular-resources/create/#compile-the-module-into-an-executable).
-
-   - To package a module written in Python, run the following command from the same directory as your `meta.json` file:
+   ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+   tar -czf module.tar.gz run.sh requirements.txt src
+   ```
 
-     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
-     tar -czf module.tar.gz run.sh requirements.txt src
-     ```
+   Where `run.sh` is your [entrypoint file](/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module.
 
-     Where `run.sh` is your [entrypoint file](/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module.
+   Supply the path to the resulting archive file in the next step.
 
-1. Run `viam module upload` to upload the updated custom module to the Viam registry:
+1. Run `viam module upload` to upload your custom module to the Viam registry:
 
    ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
-   viam module upload --version <version> --platform <platform> <path-to-tar.gz>
+   viam module upload --version <version> --platform <platform> <module-path>
    ```
 
-   For example, the following command uploads the compressed `my-module.tar.gz` archive to the Viam registry when run in the same directory, and increments the [`version`](/manage/cli/#using-the---version-argument) of the module to version `1.0.1`:
+   For example, the following command uploads a module compressed as an archive named `my-module.tar.gz` to the Viam registry, and increments the [`version`](/manage/cli/#using-the---version-argument) of the module to version `1.0.1`:
 
    ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
    viam module upload --version 1.0.1 --platform darwin/arm64 my-module.tar.gz
    ```
 
-   When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam registry.
+   When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your module to check for common errors.
 
 For more information, see the [`viam module` command](/manage/cli/#module)