[Enhancement] - Improve `news` router docs and examples (#6047)

* better docs

* static assets

30 files changed, 231 insertions, 189 deletions

diff --git a/openbb_platform/extensions/news/openbb_news/news_router.py b/openbb_platform/extensions/news/openbb_news/news_router.py
index 84005c1f146..906a31f527b 100644
--- a/openbb_platform/extensions/news/openbb_news/news_router.py
+++ b/openbb_platform/extensions/news/openbb_news/news_router.py
@@ -14,7 +14,21 @@ from openbb_core.app.router import Router
 router = Router(prefix="")
 
 
-@router.command(model="WorldNews")
+@router.command(
+    model="WorldNews",
+    examples=[
+        "# Get news on the specified dates.",
+        "obb.news.world(start_date='2024-02-01', end_date='2024-02-07')",
+        "# Display the headlines of the news.",
+        "obb.news.world(display='headline', provider='benzinga')",
+        "# Get news by topics.",
+        "obb.news.world(topics='finance', provider='benzinga')",
+        "# Get news by source using 'tingo' as provider.",
+        "obb.news.world(provider='tiingo', source='bloomberg')",
+        "# Filter aticles by term using 'biztoc' as provider.",
+        "obb.news.world(provider='biztoc', term='apple')",
+    ],
+)
 async def world(
     cc: CommandContext,
     provider_choices: ProviderChoices,
@@ -25,7 +39,19 @@ async def world(
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="CompanyNews")
+@router.command(
+    model="CompanyNews",
+    examples=[
+        "# Get news on the specified dates.",
+        "obb.news.company(symbols='AAPL', start_date='2024-02-01', end_date='2024-02-07')",
+        "# Display the headlines of the news.",
+        "obb.news.company(symbols='AAPL', display='headline', provider='benzinga')",
+        "# Get news for multiple symbols.",
+        "obb.news.company(symbols='aapl,tsla')",
+        "# Get news company's ISIN.",
+        "obb.news.company(symbols='NVDA', isin='US0378331005')",
+    ],
+)
 async def company(
     cc: CommandContext,
     provider_choices: ProviderChoices,
diff --git a/openbb_platform/openbb/package/__extensions__.py b/openbb_platform/openbb/package/__extensions__.py
index 72074831884..5afd2766c99 100644
--- a/openbb_platform/openbb/package/__extensions__.py
+++ b/openbb_platform/openbb/package/__extensions__.py
@@ -8,7 +8,6 @@ class Extensions(Container):
     # fmt: off
     """
 Routers:
-    /commodity
     /crypto
     /currency
     /derivatives
@@ -50,13 +49,8 @@ Extensions:
         return self.__doc__ or ""
 
     @property
-    def commodity(self):  # route = "/commodity"
-        from . import commodity
-
-        return commodity.ROUTER_commodity(command_runner=self._command_runner)
-
-    @property
-    def crypto(self):  # route = "/crypto"
+    def crypto(self):
+        # pylint: disable=import-outside-toplevel
         from . import crypto
 
         return crypto.ROUTER_crypto(command_runner=self._command_runner)
@@ -76,13 +70,8 @@ Extensions:
         return derivatives.ROUTER_derivatives(command_runner=self._command_runner)
 
     @property
-    def econometrics(self):  # route = "/econometrics"
-        from . import econometrics
-
-        return econometrics.ROUTER_econometrics(command_runner=self._command_runner)
-
-    @property
-    def economy(self):  # route = "/economy"
+    def economy(self):
+        # pylint: disable=import-outside-toplevel
         from . import economy
 
         return economy.ROUTER_economy(command_runner=self._command_runner)
@@ -123,19 +112,8 @@ Extensions:
         return news.ROUTER_news(command_runner=self._command_runner)
 
     @property
-    def quantitative(self):  # route = "/quantitative"
-        from . import quantitative
-
-        return quantitative.ROUTER_quantitative(command_runner=self._command_runner)
-
-    @property
-    def regulators(self):  # route = "/regulators"
+    def regulators(self):
+        # pylint: disable=import-outside-toplevel
         from . import regulators
 
         return regulators.ROUTER_regulators(command_runner=self._command_runner)
-
-    @property
-    def technical(self):  # route = "/technical"
-        from . import technical
-
-        return technical.ROUTER_technical(command_runner=self._command_runner)
diff --git a/openbb_platform/openbb/package/crypto.py b/openbb_platform/openbb/package/crypto.py
index 85a700d2531..bf09bd7fda7 100644
--- a/openbb_platform/openbb/package/crypto.py
+++ b/openbb_platform/openbb/package/crypto.py
@@ -49,7 +49,7 @@ class ROUTER_crypto(Container):
         Returns
         -------
         OBBject
-            results : List[CryptoSearch]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPCryptoSearch], Tag(tag='fmp')]]
                 Serializable results.
             provider : Optional[Literal['fmp']]
                 Provider name.
diff --git a/openbb_platform/openbb/package/crypto_price.py b/openbb_platform/openbb/package/crypto_price.py
index 76eff022221..06c9790dcca 100644
--- a/openbb_platform/openbb/package/crypto_price.py
+++ b/openbb_platform/openbb/package/crypto_price.py
@@ -59,18 +59,12 @@ class ROUTER_crypto_price(Container):
             no default.
         timeseries : Optional[Annotated[int, Ge(ge=0)]]
             Number of days to look back. (provider: fmp)
-        interval : Optional[Union[Literal['1min', '5min', '15min', '30min', '1hour', '4hour', '1day'], Literal['1m', '2m', '5m', '15m', '30m', '60m', '90m', '1h', '1d', '5d', '1wk', '1mo', '3mo']]]
-            Data granularity. (provider: fmp, tiingo, yfinance)
-        multiplier : int
-            Multiplier of the timespan. (provider: polygon)
-        timespan : Literal['minute', 'hour', 'day', 'week', 'month', 'quarter', 'year']
-            Timespan of the data. (provider: polygon)
+        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)
-        adjusted : bool
-            Whether the data is adjusted. (provider: polygon)
         exchanges : Optional[List[str]]
             To limit the query to a subset of exchanges e.g. ['POLONIEX', 'GDAX'] (provider: tiingo)
         period : Optional[Literal['1d', '5d', '1mo', '3mo', '6mo', '1y', '2y', '5y', '10y', 'ytd', 'max']]
@@ -79,7 +73,7 @@ class ROUTER_crypto_price(Container):
         Returns
         -------
         OBBject
-            results : List[CryptoHistorical]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPCryptoHistorical], Tag(tag='fmp')], Annotated[List[PolygonCryptoHistorical], Tag(tag='polygon')], Annotated[List[TiingoCryptoHistorical], Tag(tag='tiingo')], Annotated[List[YFinanceCryptoHistorical], Tag(tag='yfinance')]]
                 Serializable results.
             provider : Optional[Literal['fmp', 'polygon', 'tiingo', 'yfinance']]
                 Provider name.
diff --git a/openbb_platform/openbb/package/currency.py b/openbb_platform/openbb/package/currency.py
index bc9cb9a4bfa..a0b06550e9e 100644
--- a/openbb_platform/openbb/package/currency.py
+++ b/openbb_platform/openbb/package/currency.py
@@ -54,7 +54,7 @@ class ROUTER_currency(Container):
         Returns
         -------
         OBBject
-            results : List[CurrencyPairs]
+            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.
diff --git a/openbb_platform/openbb/package/currency_price.py b/openbb_platform/openbb/package/currency_price.py
index 1d1352ca65a..bfea88fc921 100644
--- a/openbb_platform/openbb/package/currency_price.py
+++ b/openbb_platform/openbb/package/currency_price.py
@@ -57,25 +57,19 @@ class ROUTER_currency_price(Container):
             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'], Literal['1m', '2m', '5m', '15m', '30m', '60m', '90m', '1h', '1d', '5d', '1wk', '1mo', '3mo']]]
-            Data granularity. (provider: fmp, tiingo, yfinance)
-        multiplier : int
-            Multiplier of the timespan. (provider: polygon)
-        timespan : Literal['minute', 'hour', 'day', 'week', 'month', 'quarter', 'year']
-            Timespan of the data. (provider: polygon)
+        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)
-        adjusted : bool
-            Whether the data is adjusted. (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 : List[CurrencyHistorical]
+            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.
diff --git a/openbb_platform/openbb/package/derivatives_options.py b/openbb_platform/openbb/package/derivatives_options.py
index 43077b374bb..5e5bba0ae17 100644
--- a/openbb_platform/openbb/package/derivatives_options.py
+++ b/openbb_platform/openbb/package/derivatives_options.py
@@ -45,7 +45,7 @@ class ROUTER_derivatives_options(Container):
         Returns
         -------
         OBBject
-            results : List[OptionsChains]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[IntrinioOptionsChains], Tag(tag='intrinio')]]
                 Serializable results.
             provider : Optional[Literal['intrinio']]
                 Provider name.
@@ -194,7 +194,7 @@ class ROUTER_derivatives_options(Container):
         Returns
         -------
         OBBject
-            results : List[OptionsUnusual]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[IntrinioOptionsUnusual], Tag(tag='intrinio')]]
                 Serializable results.
             provider : Optional[Literal['intrinio']]
                 Provider name.
diff --git a/openbb_platform/openbb/package/economy.py b/openbb_platform/openbb/package/economy.py
index 95cb79a8422..e7784ce4b95 100644
--- a/openbb_platform/openbb/package/economy.py
+++ b/openbb_platform/openbb/package/economy.py
@@ -69,7 +69,7 @@ class ROUTER_economy(Container):
         Returns
         -------
         OBBject
-            results : List[EconomicCalendar]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPEconomicCalendar], Tag(tag='fmp')], Annotated[List[TEEconomicCalendar], Tag(tag='tradingeconomics')]]
                 Serializable results.
             provider : Optional[Literal['fmp', 'tradingeconomics']]
                 Provider name.
@@ -178,7 +178,7 @@ class ROUTER_economy(Container):
             Returns
             -------
             OBBject
-                results : List[CLI]
+                results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[OECDCLI], Tag(tag='oecd')]]
                     Serializable results.
                 provider : Optional[Literal['oecd']]
                     Provider name.
@@ -341,7 +341,7 @@ class ROUTER_economy(Container):
         Returns
         -------
         OBBject
-            results : List[ConsumerPriceIndex]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FREDConsumerPriceIndex], Tag(tag='fred')]]
                 Serializable results.
             provider : Optional[Literal['fred']]
                 Provider name.
@@ -424,7 +424,7 @@ class ROUTER_economy(Container):
             Returns
             -------
             OBBject
-                results : List[FredSearch]
+                results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FredSearch], Tag(tag='fred')]]
                     Serializable results.
                 provider : Optional[Literal['fred']]
                     Provider name.
@@ -583,7 +583,7 @@ class ROUTER_economy(Container):
         Returns
         -------
         OBBject
-            results : List[FredSeries]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FredSeries], Tag(tag='fred')], Annotated[List[IntrinioFredSeries], Tag(tag='intrinio')]]
                 Serializable results.
             provider : Optional[Literal['fred', 'intrinio']]
                 Provider name.
@@ -677,7 +677,7 @@ class ROUTER_economy(Container):
             Returns
             -------
             OBBject
-                results : List[STIR]
+                results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[OECDSTIR], Tag(tag='oecd')]]
                     Serializable results.
                 provider : Optional[Literal['oecd']]
                     Provider name.
@@ -759,7 +759,7 @@ class ROUTER_economy(Container):
         Returns
         -------
         OBBject
-            results : List[MoneyMeasures]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FederalReserveMoneyMeasures], Tag(tag='federal_reserve')]]
                 Serializable results.
             provider : Optional[Literal['federal_reserve']]
                 Provider name.
@@ -826,7 +826,7 @@ class ROUTER_economy(Container):
         Returns
         -------
         OBBject
-            results : List[RiskPremium]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPRiskPremium], Tag(tag='fmp')]]
                 Serializable results.
             provider : Optional[Literal['fmp']]
                 Provider name.
@@ -909,7 +909,7 @@ class ROUTER_economy(Container):
             Returns
             -------
             OBBject
-                results : List[STIR]
+                results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[OECDSTIR], Tag(tag='oecd')]]
                     Serializable results.
                 provider : Optional[Literal['oecd']]
                     Provider name.
@@ -993,7 +993,7 @@ class ROUTER_economy(Container):
         Returns
         -------
         OBBject
-            results : List[Unemployment]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[OECDUnemployment], Tag(tag='oecd')]]
                 Serializable results.
             provider : Optional[Literal['oecd']]
                 Provider name.
diff --git a/openbb_platform/openbb/package/economy_gdp.py b/openbb_platform/openbb/package/economy_gdp.py
index 5cb9b376d80..7febbd6ceca 100644
--- a/openbb_platform/openbb/package/economy_gdp.py
+++ b/openbb_platform/openbb/package/economy_gdp.py
@@ -73,7 +73,7 @@ class ROUTER_economy_gdp(Container):
         Returns
         -------
         OBBject
-            results : List[GdpForecast]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[OECDGdpForecast], Tag(tag='oecd')]]
                 Serializable results.
             provider : Optional[Literal['oecd']]
                 Provider name.
@@ -157,7 +157,7 @@ class ROUTER_economy_gdp(Container):
         Returns
         -------
         OBBject
-            results : List[GdpNominal]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[OECDGdpNominal], Tag(tag='oecd')]]
                 Serializable results.
             provider : Optional[Literal['oecd']]
                 Provider name.
@@ -240,7 +240,7 @@ class ROUTER_economy_gdp(Container):
         Returns
         -------
         OBBject
-            results : List[GdpReal]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[OECDGdpReal], Tag(tag='oecd')]]
                 Serializable results.
             provider : Optional[Literal['oecd']]
                 Provider name.
diff --git a/openbb_platform/openbb/package/equity.py b/openbb_platform/openbb/package/equity.py
index d4b1a03457c..22d2ce48d19 100644
--- a/openbb_platform/openbb/package/equity.py
+++ b/openbb_platform/openbb/package/equity.py
@@ -90,7 +90,7 @@ class ROUTER_equity(Container):
         Returns
         -------
         OBBject
-            results : List[MarketSnapshots]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPMarketSnapshots], Tag(tag='fmp')], Annotated[List[PolygonMarketSnapshots], Tag(tag='polygon')]]
                 Serializable results.
             provider : Optional[Literal['fmp', 'polygon']]
                 Provider name.
@@ -241,7 +241,7 @@ class ROUTER_equity(Container):
         Returns
         -------
         OBBject
-            results : List[EquityInfo]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPEquityProfile], Tag(tag='fmp')], Annotated[List[IntrinioEquityInfo], Tag(tag='intrinio')], Annotated[List[YFinanceEquityProfile], Tag(tag='yfinance')]]
                 Serializable results.
             provider : Optional[Literal['fmp', 'intrinio', 'yfinance']]
                 Provider name.
@@ -443,7 +443,7 @@ class ROUTER_equity(Container):
         Returns
         -------
         OBBject
-            results : List[EquityScreener]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[FMPEquityScreener], Tag(tag='fmp')]]
                 Serializable results.
             provider : Optional[Literal['fmp']]
                 Provider name.
@@ -510,6 +510,10 @@ class ROUTER_equity(Container):
             bool,
             OpenBBCustomParameter(description="Whether to search by ticker symbol."),
         ] = False,
+        use_cache: Annotated[
+            Optional[bool],
+            OpenBBCustomParameter(description="Whether to use the cache or not."),
+        ] = True,
         provider: Optional[Literal["intrinio", "sec"]] = None,
         **kwargs
     ) -> OBBject:
@@ -521,6 +525,8 @@ class ROUTER_equity(Container):
             Search query.
         is_symbol : bool
             Whether to search by ticker symbol.
+        use_cache : Optional[bool]
+            Whether to use the cache or not.
         provider : Optional[Literal['intrinio', 'sec']]
             The provider to use for the query, by default None.
             If None, the provider specified in defaults is selected or 'intrinio' if there is
@@ -531,13 +537,11 @@ class ROUTER_equity(Container):
             The number of data entries to return. (provider: intrinio)
         is_fund : bool
             Whether to direct the search to the list of mutual funds and ETFs. (provider: sec)
-        use_cache : bool
-            Whether to use the cache or not. Company names, tickers, and CIKs are cached for seven days. (provider: sec)
 
         Returns
         -------
         OBBject
-            results : List[EquitySearch]
+            results : Union[Annotated[Union[list, dict], Tag(tag='openbb')], Annotated[List[IntrinioEquitySearch], Tag(tag='intrinio')], Annotated[List[SecEquitySearch], Tag(tag='sec')]]
                 Serializable results.
             provider : Optional[Literal['intrinio', 'sec']]
                 Provider name.
@@ -565,7 +569,7 @@ class ROUTER_equity(Container):
         Example
         -------
         >>> from openbb import obb
-        >>> obb.equity.search(query="AAPL", is_symbol=False)
+        >>> obb.equity.search(query="AAPL", is_symbol=False, use_cache=True)
         """  # noqa: E501
 
         return self._run(
@@ -577,6 +581,7 @@ class ROUTER_equity(Container):
                 standard_params={
                     "query": query,
                     "is_symbol": is_symbol,
+                    "use_cache": use_cache,
                 },
                 extra_params=kwargs,
             )
diff --git a/openbb_platform/openbb/package/equity_calendar.py b/openbb_platform/openbb/package/equity_calendar.py
index 42c0e0852e7..204b9d7844a 100644
--- a/openbb_platform/openbb/package/equity_calendar.py
+++ b/