Merge pull request #347 from zowe/fix-346

fix: respect common env variables

.gitignore

@@ -180,3 +180,5 @@ docs/source/classes
 # Team config files
 zowe.config*.json
 zowe.schema.json
+
+node_modules/

CHANGELOG.md

@@ -7,6 +7,7 @@ All notable changes to the Zowe Client Python SDK will be documented in this fil
 ### Enhancements
 
 - Turning off logger at the class-constructor level [#316](https://github.com/zowe/zowe-client-python-sdk/issues/316)
+- Added support for commonly used environmental variables, like `REQUESTS_CA_BUNDLE` and `CURL_CA_BUNDLE`. [#346](https://github.com/zowe/zowe-client-python-sdk/issues/346)
 
 ### Bug Fixes
 
@@ -19,7 +20,6 @@ All notable changes to the Zowe Client Python SDK will be documented in this fil
 
 - Fixed Core SDK package referencing a non-existent version of Secrets SDK.
 
-
 ## `1.0.0-dev20`
 
 ### Enhancements

docs/README.md

@@ -0,0 +1,28 @@
+# Zowe CLient Python SDK - ReadTheDocs
+
+This document is intended to help you build the documentation that will eventually make its way into the live site: [https://zowe-client-python-sdk.readthedocs.io/en/latest/index.html](https://zowe-client-python-sdk.readthedocs.io/en/latest/index.html)
+
+## Installation requirements
+
+- Python 3.13 or above: [https://www.python.org/downloads/](https://www.python.org/downloads/)
+- Sphinx: [https://www.sphinx-doc.org/en/master/usage/installation.html#os-specific-package-manager](https://www.sphinx-doc.org/en/master/usage/installation.html#os-specific-package-manager)
+  - Windows users may need to install Chocolatey: [https://chocolatey.org/install](https://chocolatey.org/install)
+    - I suggest going through the NodeJS installer and opt-in to instal Chocolatey in the final step
+    ![node-setup-choco](https://user-images.githubusercontent.com/3109072/68096791-82350c00-fe89-11e9-8cfa-b4619ce96162.jpg)
+- Enchant: (Optional) [https://pyenchant.github.io/pyenchant/install.html](https://pyenchant.github.io/pyenchant/install.html)
+
+## Build steps
+
+These steps should help you to build the documentation
+
+0. Clone the repository, open a terminal, and `cd` into the repository directory
+1. Install project dependencies:
+    - `npm install`
+2. Create a virtual environment:
+    - `npm run env:create`
+3. Activate the virtual environment:
+    - `npm run env:activate`
+4. Install the doc dependencies
+    - `npm run doc:install`
+5. Build and open the documentation:
+    - `npm run doc:dev`

docs/source/index.rst

@@ -9,8 +9,8 @@ Python developers can leverage the Zowe SDK in order to create powerful scripts/
    :maxdepth: 2
    :caption: Contents:
 
-   usage/getting-started
    about/about
+   usage/getting-started
    packages/packages
    classes/index
    contributing/contributing

docs/source/usage/advanced.rst

@@ -0,0 +1,7 @@
+Advanced steps
+===============
+
+- Use a custom Certificate Authority if working in a restricted environment.
+   The Python SDK supports the commonly used environmental variables `REQUESTS_CA_BUNDLE` and `CURL_CA_BUNDLE` to provide a certificate chain.
+
+   You can also use the `SSL_CERT_FILE` environmental variable in project-level configurations.

docs/source/usage/examples.rst

@@ -1,32 +1,37 @@
-Basic usage
+First steps
 ============
 
-After you install the package in your project, import the class for the required sub-package (i.e `Console` class for z/OS Console commands). 
-Create a dictionary to handle communication with the plug-in:
+After you install the package in your project, integrate the SDK in your script:
 
-.. code-block:: python
+1. Import the class for the required sub-package in order to call the individual SDK method and run plug-in commands. 
 
-    from zowe.zos_console_for_zowe_sdk import Console
-    profile = {
-        "host": "<host address>",
-        "port": 443, # Include the port if different from the default (443)
-        "user": "<user>",
-        "password": "<password>",
-        # "rejectUnauthorized": True, # Set to False to disable SSL verification
-        # "basePath": "", # Define base path if using Zowe API ML (e.g. "/ibmzosmf/api/v1" for z/OSMF)
-        # "protocol": "https", # Include the protocol if different from the default (https)
-    }
+    For example, the `Console` class must be imported for z/OS Console commands to be issued. 
 
-    my_console = Console(profile)
+2. Create a dictionary to add connection information to communicate with the plug-in:
 
-Alternatively you can use an existing Zowe CLI profile instead:
+    .. code-block:: python
 
-.. code-block:: python
+        from zowe.zos_console_for_zowe_sdk import Console
+        profile = {
+            "host": "<host address>",
+            "port": 443, # Include the port if different from the default (443)
+            "user": "<user>",
+            "password": "<password>",
+            # "rejectUnauthorized": True, # Set to False to disable SSL verification
+            # "basePath": "", # Define base path if using Zowe API ML (e.g. "/ibmzosmf/api/v1" for z/OSMF)
+            # "protocol": "https", # Include the protocol if different from the default (https)
+        }
 
-  from zowe.zos_console_for_zowe_sdk import Console
-  from zowe.core_for_zowe_sdk import ProfileManager
+        my_console = Console(profile)    
 
-  # Load the profile using ProfileManager
-  profile = ProfileManager().load(profile_name="<profile name>")
+    Alternatively you can use an existing Zowe CLI profile instead:
 
-  my_console = Console(profile)
+    .. code-block:: python
+
+            from zowe.zos_console_for_zowe_sdk import Console
+            from zowe.core_for_zowe_sdk import ProfileManager
+
+            # Load the profile using ProfileManager
+            profile = ProfileManager().load(profile_name="<profile name>")
+
+            my_console = Console(profile)

docs/source/usage/getting-started.rst

@@ -1,8 +1,12 @@
 Getting started
 =================
+Review the requirements and installation instructions to get started using the Zowe Client Python SDK.
 
 .. toctree::
    :maxdepth: 2
 
+   requirements
    installation
    examples
+   advanced
+

docs/source/usage/installation.rst

@@ -1,23 +1,17 @@
 Installation
 ============
+When installing the Zowe Client Python SDK you have two options:
 
-When installing the Zowe Client Python SDK you have two options.
+- Install **all Zowe packages** to install everything under the `zowe` namespace in PyPi.
+- Install a **single subpackage** for a smaller installation.
 
-- Install all the Zowe packages
-- Install a single sub-package
-
-The choice depends on your intentions. If you chose to install all Zowe SDK packages
-this means that you will install everything under the `zowe` namespace in PyPi. 
-
-Alternatively you can chose to install only a single subpackage for a smaller installation.
-
-To install all Zowe SDK packages using pip:
+To install all Zowe SDK packages using `pip`:
 
 .. code-block::
 
     pip install -U --pre zowe-python-sdk-bundle
 
-To install only a subpackage using pip:
+To install only a subpackage using `pip`:
 
 .. code-block::
 

docs/source/usage/requirements.rst

@@ -0,0 +1,8 @@
+Requirements
+=============
+
+Zowe Client Python SDK requires the following:
+
+- **Python** 3.9+ to run your script
+- (optional) **Sphinx** to build project documentation
+- (optional) **Enchant** to build project documentation