Update readme (#5449)

* update readme

* typos

* installation

* keys

* example

* minor fix

* api keys

* eg

* Update CONTRIBUTING.md

* openbb hub

* minor adjustments

---------

Co-authored-by: hjoaquim <h.joaquim@campus.fct.unl.pt>

3 files changed, 141 insertions, 131 deletions

diff --git a/openbb_sdk/CONTRIBUTING.md b/openbb_sdk/CONTRIBUTING.md
index dfe25676839..9eb9bd2e11b 100644
--- a/openbb_sdk/CONTRIBUTING.md
+++ b/openbb_sdk/CONTRIBUTING.md
@@ -25,6 +25,9 @@
       - [Add a visualization to an existing SDK command](#add-a-visualization-to-an-existing-sdk-command)
       - [Using the `to_chart` OBBject method](#using-the-to_chart-obbject-method)
   - [Environment and dependencies](#environment-and-dependencies)
+  - [Python package](#python-package)
+    - [Overview](#overview)
+    - [Import time](#import-time)
 
 ## Get started contributing with a template
 
@@ -475,3 +478,39 @@ Run `./install_all.sh` for Linux/mac or `install_all.bat` for Windows.
 </details>
 
 > In order to install any other custom extension or provider, you'd follow the exact same steps as above.
+
+## Python package
+
+### Overview
+
+One of the interfaces we provide to users is the `openbb` python package.
+
+The code you will find in this package is generated from a script and it is just a
+wrapper around the `openbb-core` and any installed extensions.
+
+When the user runs `import openbb`, `from openbb import sdk` or other variants, the
+script that generates the package code is triggered. It detects if there are new openbb
+extensions installed in the environment and rebuilds the package code accordingly. If
+new extensions are not found it just uses the current package version.
+
+When you are developing chances are you want to manually trigger the package rebuild.
+You can do that with:
+
+```python
+python -c "import openbb; openbb.build()"
+```
+
+### Import time
+
+We aim to have a short import time for the package. To measure that we use `tuna`.
+
+- https://pypi.org/project/tuna/
+
+To visualize the import time breakdown by module and find potential bottlenecks, run the
+following commands from `openbb_sdk` directory:
+
+```bash
+pip install tuna
+python -X importtime openbb/__init__.py 2> import.log
+tuna import.log
+```
diff --git a/openbb_sdk/README.md b/openbb_sdk/README.md
index b1e251edc72..c77c86ddb39 100644
--- a/openbb_sdk/README.md
+++ b/openbb_sdk/README.md
@@ -1,156 +1,106 @@
-# Table of contents
+[![Downloads](https://static.pepy.tech/badge/openbb)](https://pepy.tech/project/openbb)
+[![LatestRelease](https://badge.fury.io/py/openbb.svg)](https://github.com/OpenBB-finance/OpenBBTerminal)
 
-- [Table of contents](#table-of-contents)
-  - [Pre-requisites](#pre-requisites)
-  - [Installation](#installation)
-  - [API keys](#api-keys)
-    - [1. From local file](#1-from-local-file)
-    - [2. From runtime](#2-from-runtime)
-    - [3. From OpenBB Hub](#3-from-openbb-hub)
-  - [Python Usage](#python-usage)
-  - [API Usage](#api-usage)
-  - [Docker](#docker)
-  - [Development](#development)
-    - [Import time](#import-time)
+| OpenBB is committed to build the future of investment research by focusing on an open source infrastructure accessible to everyone, everywhere. |
+|:--:|
+| ![OpenBBLogo](https://user-images.githubusercontent.com/25267873/218899768-1f0964b8-326c-4f35-af6f-ea0946ac970b.png) |
+| Check our website at [openbb.co](www.openbb.co) |
 
-## Pre-requisites
 
-To install and use the SDK you need:
+## OpenBB Platform Overview
 
-- A fresh virtual environment
-- Python 3.8 or higher
-- API keys for the APIs you want to use
+The OpenBB Platform provides a convenient way to access raw financial data from multiple data providers. The package comes with a ready to use REST API. This allows developers from any language to easily create applications on top of OpenBB Platform.
 
-For development you need:
-
-- Poetry 1.5.1 or higher
-- ruff 0.0.256
-- mypy 1.4.1
-- black
 
 ## Installation
 
-To install the SDK in a virtual environment from the repo root run:
+The command below provides access to the core functionalities behind the [OpenBB Platform](https://my.openbb.co/app/sdk).
 
 ```bash
-pip install ./openbb_sdk
+pip install openbb
 ```
 
-This will install the SDK and all its dependencies into the site-packages directory of the virtual environment.
-
-## API keys
-
-To use your API keys you need to configure them. Here are the 3 options on how to do it:
+To install extensions that expand the core functionalities specify the extension name or use `all` to install all.
 
-1. From local file
-2. At runtime
-3. From OpenBB Hub
+```bash
+# Install single extension, e.g. openbb-charting
+pip install openbb[charting]
 
-### 1. From local file
+# Install all available extensions
+pip install openbb[all]
+``````
 
-You can specify the keys in the `~/.openbb_sdk/user_settings.json` file.
+> Note: While we are in pre-release mode you need to specify the version, e.g. `pip install openbb==4.0.0a0` or `pip install openbb[all]==4.0.0a0`
 
-Create this file using the following template and replace the values with your keys:
-
-```json
-{
-  "credentials": {
-    "fmp_api_key": "REPLACE_ME",
-    "polygon_api_key": "REPLACE_ME",
-    "benzinga_api_key": "REPLACE_ME",
-    "fred_api_key": "REPLACE_ME"
-  }
-}
-```
-
-### 2. From runtime
-
-You can also specify your keys at runtime:
+## Python
 
 ```python
-from openbb import obb
-obb.user.credentials.fmp_api_key = "REPLACE_ME"
-obb.user.credentials.polygon_api_key = "REPLACE_ME"
+>>> from openbb import obb
+>>> output = obb.stocks.load("AAPL")
+>>> df = output.to_dataframe()
+>>> df.head()
+              open    high     low  ...  change_percent             label  change_over_time
+date                                ...
+2022-09-19  149.31  154.56  149.10  ...         3.46000  September 19, 22          0.034600
+2022-09-20  153.40  158.08  153.08  ...         2.28000  September 20, 22          0.022800
+2022-09-21  157.34  158.74  153.60  ...        -2.30000  September 21, 22         -0.023000
+2022-09-22  152.38  154.47  150.91  ...         0.23625  September 22, 22          0.002363
+2022-09-23  151.19  151.47  148.56  ...        -0.50268  September 23, 22         -0.005027
+
+[5 rows x 12 columns]
 ```
 
-### 3. From OpenBB Hub
+## API keys
 
-You can also load your the keys from the OpenBB Hub.
+To fully leverage the OpenBB Platform you need to get some API keys to connect with data providers. Here are the 3 options on where to set them:
 
-```python
-from openbb import obb
-openbb.account.login(username="REPLACE_ME", password="REPLACE_ME")
-```
+1. OpenBB Hub
+2. Runtime
+3. Local file
 
-## Python Usage
+### 1. OpenBB Hub
 
-Import and basic usage:
+Set your keys at [OpenBB Hub](https://my.openbb.co/app/sdk/api-keys) and get your personal access token from https://my.openbb.co/app/sdk/pat to connect with your account.
 
 ```python
-from openbb import obb
-aapl = obb.stocks.load("AAPL")
-df = aapl.to_dataframe()
-df.head()
+>>> from openbb import obb
+>>> openbb.account.login(pat="OPENBB_PAT")
 ```
 
-## API Usage
-
-Launch the API with:
-
-```bash
-uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload
-```
-
-Navigate to <http://0.0.0.0:8000/docs> to see the swagger API documentation.
-
-Authorize with the developer credentials: openbb/openbb
+### 2. Runtime
 
-## Docker
-
-You can use the API through Docker.
-
-To build the image, from the repo root run:
+```python
+>>> from openbb import obb
+>>> obb.user.credentials.fmp_api_key = "REPLACE_ME"
+>>> obb.user.credentials.polygon_api_key = "REPLACE_ME"
 
-```bash
-docker build -f build/docker/api.dockerfile -t openbb-sdk:latest .
+>>> # Persist changes in ~/.openbb_sdk/user_settings.json
+>>> obb.account.save()
 ```
 
-To run this newly-built image:
-
-```bash
-docker run --rm -p8000:8000 -v ~/.openbb_sdk:/root/.openbb_sdk openbb-sdk:latest
-```
+### 3. Local file
 
-This will mount the local `~/.openbb_sdk` directory into the Docker container so you can use the API keys from there and it will expose the API on port `8000`.
+You can specify the keys directly in the `~/.openbb_sdk/user_settings.json` file.
 
-## Development
+Populate this file with the following template and replace the values with your keys:
 
-From the root of the OpenBB Terminal repo, run:
-
-`poetry install -C ./openbb_sdk`
-
-When developing a specific extension `cd` into the extension directory and run:
-
-`pip install -U -e .`
-
-While we're still developing, it is often required to reinstall extensions:
-
-```python
-python -c "import openbb; openbb.build()"
+```json
+{
+  "credentials": {
+    "fmp_api_key": "REPLACE_ME",
+    "polygon_api_key": "REPLACE_ME",
+    "benzinga_api_key": "REPLACE_ME",
+    "fred_api_key": "REPLACE_ME"
+  }
+}
 ```
 
-You need to do this every time you install or uninstall a new extension or to reinstall all extensions.
-
-### Import time
+## REST API
 
-We aim to have a short import time. To measure that we use `tuna`.
-
-- https://pypi.org/project/tuna/
-
-To visualize the import time breakdown by module, run the following commands from `openbb_sdk` directory:
+The OpenBB Platform comes with a ready to use REST API built with FastAPI. Start the application using this command:
 
 ```bash
-pip install tuna
-python -X importtime openbb/__init__.py 2> import.log
-tuna import.log
+uvicorn openbb_core.api.rest_api:app
 ```
+
+Check `openbb-core` [README](https://pypi.org/project/openbb-core/) for additional info.
diff --git a/openbb_sdk/sdk/core/README.md b/openbb_sdk/sdk/core/README.md
index d6689a6ae2d..c6db1e798f6 100644
--- a/openbb_sdk/sdk/core/README.md
+++ b/openbb_sdk/sdk/core/README.md
@@ -24,7 +24,8 @@
   - [4.2 Dynamic version](#42-dynamic-version)
   - [5. REST API](#5-rest-api)
     - [5.1 HTTPS](#51-https)
-    - [5.2 Test users](#52-test-users)
+    - [5.2 Docker](#52-docker)
+    - [5.3 Test users](#53-test-users)
   - [6. Front-end typing](#6-front-end-typing)
 
 ## 1. Introduction
@@ -146,7 +147,7 @@ Update your system settings by modifying the `.openbb_sdk/system_settings.json`
 
 ```{json}
 {
-    "dbms_uri": null
+    "test_mode": true
 }
 ```
 
@@ -162,7 +163,7 @@ output = obb.stocks.load(
     start_date="2023-01-01",
     provider="fmp",
     chart=True
-    )
+)
 ```
 
 ### 4.1.1. OBBject
@@ -368,18 +369,18 @@ In fact, the static version makes use of this feature to run each command. Take
 >>> from openbb_core.app.command_runner import CommandRunner
 >>> runner = CommandRunner()
 >>> output = runner.run(
-             "/stocks/load",
-             provider_choices={
-                 "provider": "fmp",
-             },
-             standard_params={
-                 "symbol": "TSLA",
-                 "start_date": "2023-07-01",
-                 "end_date": "2023-07-25",
-             },
-             extra_params={},
-             chart=True,
-         )
+    "/stocks/load",
+    provider_choices={
+        "provider": "fmp",
+    },
+    standard_params={
+        "symbol": "TSLA",
+        "start_date": "2023-07-01",
+        "end_date": "2023-07-25",
+    },
+    extra_params={},
+    chart=True,
+)
 >>> output
 OBBject
 
@@ -438,7 +439,27 @@ If you want to run your FastAPI app over HTTPS locally you can use [mkcert](http
 
     Your app will be available at https://127.0.0.1:8000/
 
-### 5.2 Test users
+### 5.2 Docker
+
+You can use the API through Docker.
+
+We provide a `.dockerfile`` in OpenBB [repo](https://github.com/OpenBB-finance/OpenBBTerminal).
+
+To build the image, you can run the following command from the repo root:
+
+```bash
+docker build -f build/docker/api.dockerfile -t openbb-sdk:latest .
+```
+
+To run this newly-built image:
+
+```bash
+docker run --rm -p 8000:8000 -v ~/.openbb_sdk:/root/.openbb_sdk openbb-sdk:latest
+```
+
+This will mount the local `~/.openbb_sdk` directory into the Docker container so you can use the API keys from there and it will expose the API on port `8000`.
+
+### 5.3 Test users
 
 There are 2 default users for testing purpose: