Update 'pipeline components' topic in the 'user guide'

docs/source/user_guide/pipeline-components.md

@@ -40,9 +40,32 @@ There are many example custom components available that you can utilize in pipel
 
 Note: Refer to the [_Requirements and best practices for custom pipeline components_ topic in the _User Guide_](best-practices-custom-pipeline-components.md) to learn more about special considerations for custom components.
 
+#### Component catalogs
+
+Elyra does not include its own component repository. Instead you can configure it to pull components from local or remote catalogs, such as file systems, web resources, or source control systems. Elyra defines a connector API, which provides access to the catalogs resources.
+
+![component catalogs](../images/user_guide/pipeline-components/component-catalogs.png)
+
+Elyra includes connectors for the following component catalog types:
+ - _Filesystem component catalogs_ provide access to components that are stored in a file system that is readable by JupyterLab/Elyra.
+
+   Example: A filesystem component catalog that is configured using the `/users/jdoe/kubeflow_components/dev/my_component.yaml` path makes `my_component.yaml` available to Elyra.
+
+ - _Directory component catalogs_ provide access to components that are stored in a directory.
+
+   Example: A directory component catalog that is configured using the `/users/jdoe/kubeflow_components/test` path makes all component files in that directory available to Elyra.
+
+ - _URL component catalogs_ provide access to components that are stored on the web and can be retrieved using anonymous HTTP `GET` requests.
+
+    Example: A URL component catalog that is configured using the `http://myserver:myport/mypath/my_component.yaml` URL makes the `my_component.yaml` component file available to Elyra.
+
+Refer to section [Built-in catalog connector reference](#built-in-catalog-connector-reference) for details about these connectors. 
+
+You can add support for other component catalogs by installing a connector from the [catalog connector marketplace](https://github.com/elyra-ai/examples/tree/master/component-catalog-connectors/marketplace.md) or by [implementing your own catalog connector](https://github.com/elyra-ai/examples/tree/master/component-catalog-connectors).
+
 #### Example custom components
 
-For illustrative purposes the Elyra component registry includes a few custom components that you can use to get started. These example components and the generic components are pre-loaded into the pipeline editor palette by default.
+For illustrative purposes the Elyra includes a few custom components that you can use to get started. These example components and the generic components are pre-loaded into the pipeline editor palette by default.
 
 ![Example pipeline for the HTTP component](../images/user_guide/pipeline-components/example-components-pipeline.png)
 
@@ -80,23 +103,24 @@ To access the panel in JupyterLab:
 
   ![Open panel from command palette](../images/user_guide/pipeline-components/cmd-palette.png)
 
-#### Adding components to the registry
+#### Adding a component catalog
 
-To add a component registry entry: 
+To add components from a catalog:
 
 1. Click `+` in the _Pipeline Components_ panel.
+1. Select a component catalog type from the list of available options.
 1. Define the registry entry. Refer to section [Configuration properties](#configuration-properties) for a description of each property.
 
 If the registry entry validates correctly, the associated pipeline components are added  to the pipeline editor's palette. 
 
-#### Modifying a component registry entry
+#### Modifying a component catalog entry
 
 1. Click the `edit` (pencil) icon next to the entry name.
 1. Modify the registry entry as desired.
 
-#### Deleting components from the registry
+#### Deleting a component catalog from the registry
 
-To delete a component registry entry and its referenced component(s) from the Visual Pipeline Editor palette:
+To delete a component catalog entry and its referenced component(s) from the Visual Pipeline Editor palette:
 
 1. Click the `delete` (trash) icon next to the entry name.
 1. Confirm deletion.
@@ -206,31 +230,53 @@ Example:
 
 - `airflow`
 
-##### Location Type (location_type)
+### Built-in catalog connector reference
 
-The location type identifies the format that the value(s) provided in `Paths` represent. Supported types are `URL`, `Filename`, or `Directory`. This property is required.
+Elyra supports fetching components from the file system and the web using its built-in connectors. 
 
-- `URL`: The provided `Paths` identify web resources. The pipeline editor loads the specified URLs using anonymous HTTP `GET` requests.
-- `Filename`: The provided absolute `Paths` identify files in the file system where JupyterLab/Elyra is running. `~` may be used to denote the user's home directory.
-- `Directory`: The provided absolute `Paths` must identify existing directories in the file system where JupyterLab/Elyra is running. `~` may be used to denote the user's home directory. The pipeline editor scans the specified directories for component specifications. Scans are not performed recursively.
+#### Filesystem component catalog
 
-##### Paths (paths)
+The filesystem component catalog connector provides access to components that are stored in the file system where Elyra is running:
+ - `~` may be used to denote the user's home directory.
+ - Wildcards (e.g. `*` or `?`) are not supported.
+ - You can specify one or more file names.
+ - Best practice: Pipeline files include references to the location from where components were loaded. When adding files to the catalog, specify a `base directory` and a relative file path to make pipelines portable across environments.
 
-A path defines the location from where the pipeline editor loads one or more component specifications. The provided value must be a valid representation of the selected _location type_. This property is required.
+Examples (GUI):
+ - `/Users/patti/specs/load_data_from_public_source/http_operator.py`
+ - `~patti/specs/filter_files/row_filter.yaml`
+
+Examples (CLI):
+ - `['/Users/patti/specs/load_data_from_public_source/http_operator.py']`
+ - `['~patti/specs/filter_files/row_filter.yaml']`
+ - `['/Users/patti/specs/comp1.yaml','/Users/patti/specs/comp2.yaml']`
+
+#### Directory component catalog
+
+The directory component catalog connector provides access to components that are stored in a file system directory: 
+ - If `Path` is set to `/Users/patti/specs/load_from_database`, the connector searches  the specified directory for components for the selected runtime type.
+ - The search is performed recursively if the subdirectory option is enabled.
+ - `~` may be used to denote the user's home directory.
+ - You can specify one or more directories.
 
 Examples (GUI):
- - URL: `https://raw.githubusercontent.com/elyra-ai/elyra/master/etc/config/components/kfp/run_notebook_using_papermill.yaml`
- - Filename: `/Users/patti/specs/load_data_from_public_source/http_operator.py`
- - Filename: `~patti/specs/filter_files/row_filter.yaml`
- - Directory: `/Users/patti/specs/load_from_database`
-
- Examples (CLI):
- - URL: `['https://raw.githubusercontent.com/elyra-ai/elyra/master/etc/config/components/kfp/run_notebook_using_papermill.yaml']`
- - Filename: `['/Users/patti/specs/load_data_from_public_source/http_operator.py']`
- - Filename: `['~patti/specs/filter_files/row_filter.yaml']`
- - Directory: `['/Users/patti/specs/load_from_database']`
-
- Examples multiple components (CLI):
- - URL: `['URL1', 'URL2']`
- - Filename: `['/Users/patti/specs/comp1.yaml','/Users/patti/specs/comp2.yaml']`
- - Directory: `['/Users/patti/load_specs/','/Users/patti/cleanse_specs/']`
+ - `/Users/patti/specs/load_from_database`
+ - `~patti/specs/load_from_cloud_storage`
+
+Examples (CLI):
+ - `['/Users/patti/specs/load_from_database']`
+ - `['~patti/specs/load_from_cloud_storage']`
+ - `['/Users/patti/load_specs/','/Users/patti/cleanse_specs/']` 
+
+#### URL component catalog
+
+The URL component catalog connector provides access to components that are stored on the web:
+- The specified URL must be retrievable using an anonymous HTTP `GET` request.
+- You can specify one or more URLs.
+
+Examples (GUI):
+ - `https://raw.githubusercontent.com/elyra-ai/elyra/master/etc/config/components/kfp/run_notebook_using_papermill.yaml`
+
+Examples (CLI):
+ - `['https://raw.githubusercontent.com/elyra-ai/elyra/master/etc/config/components/kfp/run_notebook_using_papermill.yaml']`
+ - `['<URL_1>','<URL_2>']`