[Enhancement] - Improve `currency` router docs and examples (#6045)

* currency search

* reference rates

* historical price

* static assets

---------

Co-authored-by: montezdesousa <79287829+montezdesousa@users.noreply.github.com>

4 files changed, 216 insertions, 143 deletions

diff --git a/openbb_platform/extensions/currency/openbb_currency/currency_router.py b/openbb_platform/extensions/currency/openbb_currency/currency_router.py
index cfb591a4e3b..e7ef5d46f7c 100644
--- a/openbb_platform/extensions/currency/openbb_currency/currency_router.py
+++ b/openbb_platform/extensions/currency/openbb_currency/currency_router.py
@@ -17,14 +17,34 @@ router.include_router(price_router)
 
 
 # pylint: disable=unused-argument
-@router.command(model="CurrencyPairs")
+@router.command(
+    model="CurrencyPairs",
+    examples=[
+        "# Search for 'EURUSD' currency pair using 'polygon' as provider.",
+        "obb.currency.search(provider='polygon', symbol='EURUSD')",
+        "# Search for terms  using 'polygon' as provider.",
+        "obb.currency.search(provider='polygon', search='Euro zone')",
+        "# Search for actively traded currency pairs on the queried date using 'polygon' as provider.",
+        "obb.currency.search(provider='polygon', date='2024-01-02', active=True)",
+    ],
+)
 async def search(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Currency Search. Search available currency pairs."""
+    """
+    Currency Search.
+
+    Search available currency pairs.
+    Currency pairs are the national currencies from two countries coupled for trading on
+    the foreign exchange (FX) marketplace.
+    Both currencies will have exchange rates on which the trade will have its position basis.
+    All trading within the forex market, whether selling, buying, or trading, will take place through currency pairs.
+    (ref: Investopedia)
+    Major currency pairs include pairs such as EUR/USD, USD/JPY, GBP/USD, etc.
+    """
     return await OBBject.from_query(Query(**locals()))
 
 
@@ -35,5 +55,14 @@ async def reference_rates(
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Current, official, currency reference rates."""
+    """Current, official, currency reference rates.
+
+    Foreign exchange reference rates are the exchange rates set by a major financial institution or regulatory body,
+    serving as a benchmark for the value of currencies around the world.
+    These rates are used as a standard to facilitate international trade and financial transactions,
+    ensuring consistency and reliability in currency conversion.
+    They are typically updated on a daily basis and reflect the market conditions at a specific time.
+    Central banks and financial institutions often use these rates to guide their own exchange rates,
+    impacting global trade, loans, and investments.
+    """
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/extensions/currency/openbb_currency/price/price_router.py b/openbb_platform/extensions/currency/openbb_currency/price/price_router.py
index 955c19be74b..86b029b720d 100644
--- a/openbb_platform/extensions/currency/openbb_currency/price/price_router.py
+++ b/openbb_platform/extensions/currency/openbb_currency/price/price_router.py
@@ -15,12 +15,28 @@ router = Router(prefix="/price")
 
 
 # pylint: disable=unused-argument
-@router.command(model="CurrencyHistorical")
+@router.command(
+    model="CurrencyHistorical",
+    examples=[
+        "# Filter historical data with specific start and end date.",
+        "obb.currency.price.historical(symbol='EURUSD', start_date='2023-01-01', end_date='20213-12-31')",
+        "# Get data with different granularity.",
+        "obb.currency.price.historical(symbol='EURUSD', interval='15m', provider='polygon')",
+    ],
+)
 async def historical(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Currency Historical Price. Currency historical data."""
+    """
+    Currency Historical Price. Currency historical data.
+
+    Currency historical prices refer to the past exchange rates of one currency against
+    another over a specific period.
+    This data provides insight into the fluctuations and trends in the foreign exchange market,
+    helping analysts, traders, and economists understand currency performance,
+    evaluate economic health, and make predictions about future movements.
+    """
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/openbb/package/currency.py b/openbb_platform/openbb/package/currency.py
index a0b06550e9e..b9f97368152 100644
--- a/openbb_platform/openbb/package/currency.py
+++ b/openbb_platform/openbb/package/currency.py
@@ -28,82 +28,98 @@ class ROUTER_currency(Container):
     def search(
         self, provider: Optional[Literal["fmp", "intrinio", "polygon"]] = None, **kwargs
     ) -> OBBject:
-        """Currency Search. Search available currency pairs.
+        """
+        Currency Search.
 
-        Parameters
-        ----------
-        provider : Optional[Literal['fmp', 'intrinio', 'polygon']]
-            The provider to use for the query, by default None.
-            If None, the provider specified in defaults is selected or 'fmp' if there is
-            no default.
-        symbol : Optional[str]
-            Symbol of the pair to search. (provider: polygon)
-        date : Optional[datetime.date]
-            A specific date to get data for. (provider: polygon)
-        search : Optional[str]
-            Search for terms within the ticker and/or company name. (provider: polygon)
-        active : Optional[bool]
-            Specify if the tickers returned should be actively traded on the queried date. (provider: polygon)
-        order : Optional[Literal['asc', 'desc']]
-            Order data by ascending or descending. (provider: polygon)
-        sort : Optional[Literal['ticker', 'name', 'market', 'locale', 'currency_symbol', 'currency_name', 'base_currency_symbol', 'base_currency_name', 'last_updated_utc', 'delisted_utc']]
-            Sort field used for ordering. (provider: polygon)
-        limit : Optional[Annotated[int, Gt(gt=0)]]
-            The number of data entries to return. (provider: polygon)
+        Search available currency pairs.
+        Currency pairs are the national currencies from two countries coupled for trading on
+        the foreign exchange (FX) marketplace.
+        Both currencies will have exchange rates on which the trade will have its position basis.
+        All trading within the forex market, whether selling, buying, or trading, will take place through currency pairs.
+        (ref: Investopedia)
+        Major currency pairs include pairs such as EUR/USD, USD/JPY, GBP/USD, etc.
 
-        Returns
-        -------
-        OBBject
-            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPCurrencyPairs], Tag(tag='fmp')], Annotated[List[IntrinioCurrencyPairs], Tag(tag='intrinio')], Annotated[List[PolygonCurrencyPairs], Tag(tag='polygon')]]
-                Serializable results.
+
+            Parameters
+            ----------
             provider : Optional[Literal['fmp', 'intrinio', 'polygon']]
-                Provider name.
-            warnings : Optional[List[Warning_]]
-                List of warnings.
-            chart : Optional[Chart]
-                Chart object.
-            extra: Dict[str, Any]
-                Extra info.
+                The provider to use for the query, by default None.
+                If None, the provider specified in defaults is selected or 'fmp' if there is
+                no default.
+            symbol : Optional[str]
+                Symbol of the pair to search. (provider: polygon)
+            date : Optional[datetime.date]
+                A specific date to get data for. (provider: polygon)
+            search : Optional[str]
+                Search for terms within the ticker and/or company name. (provider: polygon)
+            active : Optional[bool]
+                Specify if the tickers returned should be actively traded on the queried date. (provider: polygon)
+            order : Optional[Literal['asc', 'desc']]
+                Order data by ascending or descending. (provider: polygon)
+            sort : Optional[Literal['ticker', 'name', 'market', 'locale', 'currency_symbol', 'currency_name', 'base_currency_symbol', 'base_currency_name', 'last_updated_utc', 'delisted_utc']]
+                Sort field used for ordering. (provider: polygon)
+            limit : Optional[Annotated[int, Gt(gt=0)]]
+                The number of data entries to return. (provider: polygon)
+
+            Returns
+            -------
+            OBBject
+                results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPCurrencyPairs], Tag(tag='fmp')], Annotated[List[IntrinioCurrencyPairs], Tag(tag='intrinio')], Annotated[List[PolygonCurrencyPairs], Tag(tag='polygon')]]
+                    Serializable results.
+                provider : Optional[Literal['fmp', 'intrinio', 'polygon']]
+                    Provider name.
+                warnings : Optional[List[Warning_]]
+                    List of warnings.
+                chart : Optional[Chart]
+                    Chart object.
+                extra: Dict[str, Any]
+                    Extra info.
 
-        CurrencyPairs
-        -------------
-        name : str
-            Name of the currency pair.
-        symbol : Optional[str]
-            Symbol of the currency pair. (provider: fmp)
-        currency : Optional[str]
-            Base currency of the currency pair. (provider: fmp)
-        stock_exchange : Optional[str]
-            Stock exchange of the currency pair. (provider: fmp)
-        exchange_short_name : Optional[str]
-            Short name of the stock exchange of the currency pair. (provider: fmp)
-        code : Optional[str]
-            Code of the currency pair. (provider: intrinio)
-        base_currency : Optional[str]
-            ISO 4217 currency code of the base currency. (provider: intrinio)
-        quote_currency : Optional[str]
-            ISO 4217 currency code of the quote currency. (provider: intrinio)
-        market : Optional[str]
-            Name of the trading market. Always 'fx'. (provider: polygon)
-        locale : Optional[str]
-            Locale of the currency pair. (provider: polygon)
-        currency_symbol : Optional[str]
-            The symbol of the quote currency. (provider: polygon)
-        currency_name : Optional[str]
-            Name of the quote currency. (provider: polygon)
-        base_currency_symbol : Optional[str]
-            The symbol of the base currency. (provider: polygon)
-        base_currency_name : Optional[str]
-            Name of the base currency. (provider: polygon)
-        last_updated_utc : Optional[datetime]
-            The last updated timestamp in UTC. (provider: polygon)
-        delisted_utc : Optional[datetime]
-            The delisted timestamp in UTC. (provider: polygon)
+            CurrencyPairs
+            -------------
+            name : str
+                Name of the currency pair.
+            symbol : Optional[str]
+                Symbol of the currency pair. (provider: fmp)
+            currency : Optional[str]
+                Base currency of the currency pair. (provider: fmp)
+            stock_exchange : Optional[str]
+                Stock exchange of the currency pair. (provider: fmp)
+            exchange_short_name : Optional[str]
+                Short name of the stock exchange of the currency pair. (provider: fmp)
+            code : Optional[str]
+                Code of the currency pair. (provider: intrinio)
+            base_currency : Optional[str]
+                ISO 4217 currency code of the base currency. (provider: intrinio)
+            quote_currency : Optional[str]
+                ISO 4217 currency code of the quote currency. (provider: intrinio)
+            market : Optional[str]
+                Name of the trading market. Always 'fx'. (provider: polygon)
+            locale : Optional[str]
+                Locale of the currency pair. (provider: polygon)
+            currency_symbol : Optional[str]
+                The symbol of the quote currency. (provider: polygon)
+            currency_name : Optional[str]
+                Name of the quote currency. (provider: polygon)
+            base_currency_symbol : Optional[str]
+                The symbol of the base currency. (provider: polygon)
+            base_currency_name : Optional[str]
+                Name of the base currency. (provider: polygon)
+            last_updated_utc : Optional[datetime]
+                The last updated timestamp in UTC. (provider: polygon)
+            delisted_utc : Optional[datetime]
+                The delisted timestamp in UTC. (provider: polygon)
 
-        Example
-        -------
-        >>> from openbb import obb
-        >>> obb.currency.search()
+            Example
+            -------
+            >>> from openbb import obb
+            >>> obb.currency.search()
+            >>> # Search for 'EURUSD' currency pair using 'polygon' as provider.
+            >>> obb.currency.search(provider='polygon', symbol='EURUSD')
+            >>> # Search for terms  using 'polygon' as provider.
+            >>> obb.currency.search(provider='polygon', search='Euro zone')
+            >>> # Search for actively traded currency pairs on the queried date using 'polygon' as provider.
+            >>> obb.currency.search(provider='polygon', date='2024-01-02', active=True)
         """  # noqa: E501
 
         return self._run(
diff --git a/openbb_platform/openbb/package/currency_price.py b/openbb_platform/openbb/package/currency_price.py
index bfea88fc921..0301e483613 100644
--- a/openbb_platform/openbb/package/currency_price.py
+++ b/openbb_platform/openbb/package/currency_price.py
@@ -43,78 +43,90 @@ class ROUTER_currency_price(Container):
         provider: Optional[Literal["fmp", "polygon", "tiingo", "yfinance"]] = None,
         **kwargs
     ) -> OBBject:
-        """Currency Historical Price. Currency historical data.
+        """
+        Currency Historical Price. Currency historical data.
 
-        Parameters
-        ----------
-        symbol : str
-            Symbol to get data for. Can use CURR1-CURR2 or CURR1CURR2 format.
-        start_date : Optional[datetime.date]
-            Start date of the data, in YYYY-MM-DD format.
-        end_date : Optional[datetime.date]
-            End date of the data, in YYYY-MM-DD format.
-        provider : Optional[Literal['fmp', 'polygon', 'tiingo', 'yfinance']]
-            The provider to use for the query, by default None.
-            If None, the provider specified in defaults is selected or 'fmp' if there is
-            no default.
-        interval : Optional[Union[Literal['1min', '5min', '15min', '30min', '1hour', '4hour', '1day'], str, Literal['1m', '2m', '5m', '15m', '30m', '60m', '90m', '1h', '1d', '5d', '1wk', '1mo', '3mo']]]
-            Data granularity. (provider: fmp, polygon, tiingo, yfinance)
-        sort : Literal['asc', 'desc']
-            Sort order of the data. (provider: polygon)
-        limit : int
-            The number of data entries to return. (provider: polygon)
-        period : Optional[Literal['1d', '5d', '1mo', '3mo', '6mo', '1y', '2y', '5y', '10y', 'ytd', 'max']]
-            Time period of the data to return. (provider: yfinance)
+        Currency historical prices refer to the past exchange rates of one currency against
+        another over a specific period.
+        This data provides insight into the fluctuations and trends in the foreign exchange market,
+        helping analysts, traders, and economists understand currency performance,
+        evaluate economic health, and make predictions about future movements.
 
-        Returns
-        -------
-        OBBject
-            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPCurrencyHistorical], Tag(tag='fmp')], Annotated[List[PolygonCurrencyHistorical], Tag(tag='polygon')], Annotated[List[TiingoCurrencyHistorical], Tag(tag='tiingo')], Annotated[List[YFinanceCurrencyHistorical], Tag(tag='yfinance')]]
-                Serializable results.
+
+            Parameters
+            ----------
+            symbol : str
+                Symbol to get data for. Can use CURR1-CURR2 or CURR1CURR2 format.
+            start_date : Optional[datetime.date]
+                Start date of the data, in YYYY-MM-DD format.
+            end_date : Optional[datetime.date]
+                End date of the data, in YYYY-MM-DD format.
             provider : Optional[Literal['fmp', 'polygon', 'tiingo', 'yfinance']]
-                Provider name.
-            warnings : Optional[List[Warning_]]
-                List of warnings.
-            chart : Optional[Chart]
-                Chart object.
-            extra: Dict[str, Any]
-                Extra info.
+                The provider to use for the query, by default None.
+                If None, the provider specified in defaults is selected or 'fmp' if there is
+                no default.
+            interval : Optional[Union[Literal['1min', '5min', '15min', '30min', '1hour', '4hour', '1day'], str, Literal['1m', '2m', '5m', '15m', '30m', '60m', '90m', '1h', '1d', '5d', '1wk', '1mo', '3mo']]]
+                Data granularity. (provider: fmp, polygon, tiingo, yfinance)
+            sort : Literal['asc', 'desc']
+                Sort order of the data. (provider: polygon)
+            limit : int
+                The number of data entries to return. (provider: polygon)
+            period : Optional[Literal['1d', '5d', '1mo', '3mo', '6mo', '1y', '2y', '5y', '10y', 'ytd', 'max']]
+                Time period of the data to return. (provider: yfinance)
+
+            Returns
+            -------
+            OBBject
+                results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPCurrencyHistorical], Tag(tag='fmp')], Annotated[List[PolygonCurrencyHistorical], Tag(tag='polygon')], Annotated[List[TiingoCurrencyHistorical], Tag(tag='tiingo')], Annotated[List[YFinanceCurrencyHistorical], Tag(tag='yfinance')]]
+                    Serializable results.
+                provider : Optional[Literal['fmp', 'polygon', 'tiingo', 'yfinance']]
+                    Provider name.
+                warnings : Optional[List[Warning_]]
+                    List of warnings.
+                chart : Optional[Chart]
+                    Chart object.
+                extra: Dict[str, Any]
+                    Extra info.
 
-        CurrencyHistorical
-        ------------------
-        date : datetime
-            The date of the data.
-        open : float
-            The open price.
-        high : float
-            The high price.
-        low : float
-            The low price.
-        close : float
-            The close price.
-        volume : Optional[float]
-            The trading volume.
-        vwap : Optional[Annotated[float, Gt(gt=0)]]
-            Volume Weighted Average Price over the period.
-        adj_close : Optional[float]
-            The adjusted close price. (provider: fmp)
-        unadjusted_volume : Optional[float]
-            Unadjusted volume of the symbol. (provider: fmp)
-        change : Optional[float]
-            Change in the price of the symbol from the previous day. (provider: fmp)
-        change_percent : Optional[float]
-            Change % in the price of the symbol. (provider: fmp)
-        label : Optional[str]
-            Human readable format of the date. (provider: fmp)
-        change_over_time : Optional[float]
-            Change % in the price of the symbol over a period of time. (provider: fmp)
-        transactions : Optional[Annotated[int, Gt(gt=0)]]
-            Number of transactions for the symbol in the time period. (provider: polygon)
+            CurrencyHistorical
+            ------------------
+            date : datetime
+                The date of the data.
+            open : float
+                The open price.
+            high : float
+                The high price.
+            low : float
+                The low price.
+            close : float
+                The close price.
+            volume : Optional[float]
+                The trading volume.
+            vwap : Optional[Annotated[float, Gt(gt=0)]]
+                Volume Weighted Average Price over the period.
+            adj_close : Optional[float]
+                The adjusted close price. (provider: fmp)
+            unadjusted_volume : Optional[float]
+                Unadjusted volume of the symbol. (provider: fmp)
+            change : Optional[float]
+                Change in the price of the symbol from the previous day. (provider: fmp)
+            change_percent : Optional[float]
+                Change % in the price of the symbol. (provider: fmp)
+            label : Optional[str]
+                Human readable format of the date. (provider: fmp)
+            change_over_time : Optional[float]
+                Change % in the price of the symbol over a period of time. (provider: fmp)
+            transactions : Optional[Annotated[int, Gt(gt=0)]]
+                Number of transactions for the symbol in the time period. (provider: polygon)
 
-        Example
-        -------
-        >>> from openbb import obb
-        >>> obb.currency.price.historical(symbol="EURUSD")
+            Example
+            -------
+            >>> from openbb import obb
+            >>> obb.currency.price.historical(symbol="EURUSD")
+            >>> # Filter historical data with specific start and end date.
+            >>> obb.currency.price.historical(symbol='EURUSD', start_date='2023-01-01', end_date='20213-12-31')
+            >>> # Get data with different granularity.
+            >>> obb.currency.price.historical(symbol='EURUSD', interval='15m', provider='polygon')
         """  # noqa: E501
 
         return self._run(