[Enhancement] Add function examples to Regulators Router (#6054)

* options router

* fixedincome router

* futures router

* missing comma

* static assets

* futures router

* sec router

* cftc router

* black

---------

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

3 files changed, 108 insertions, 25 deletions

diff --git a/openbb_platform/extensions/regulators/openbb_regulators/cftc/cftc_router.py b/openbb_platform/extensions/regulators/openbb_regulators/cftc/cftc_router.py
index 331757ebded..4ed99f21965 100644
--- a/openbb_platform/extensions/regulators/openbb_regulators/cftc/cftc_router.py
+++ b/openbb_platform/extensions/regulators/openbb_regulators/cftc/cftc_router.py
@@ -14,7 +14,13 @@ from openbb_core.app.router import Router
 router = Router(prefix="/cftc")
 
 
-@router.command(model="COTSearch")
+@router.command(
+    model="COTSearch",
+    exclude_auto_examples=True,
+    examples=[
+        'obb.regulators.cftc.cot_search(query="gold")',
+    ],
+)
 async def cot_search(
     cc: CommandContext,
     provider_choices: ProviderChoices,
@@ -28,12 +34,22 @@ async def cot_search(
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="COT")
+@router.command(
+    model="COT",
+    exclude_auto_examples=True,
+    examples=[
+        'obb.regulators.cftc.cot(series_id="GC=F").to_df()',
+        "#### Enter the report ID by the Nasdaq Data Link Code. ####",
+        'obb.regulators.cftc.cot(series_id="088691").to_df()',
+        "### Get the report for futures only. ####",
+        'obb.regulators.cftc.cot(series_id="088691", data_type="F").to_df()',
+    ],
+)
 async def cot(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Commitment of Traders Reports. Lookup Commitment of Traders Reports by series ID."""
+    """Commitment of Traders Reports."""
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/extensions/regulators/openbb_regulators/sec/sec_router.py b/openbb_platform/extensions/regulators/openbb_regulators/sec/sec_router.py
index b0742c7f9aa..cd03a1c53a0 100644
--- a/openbb_platform/extensions/regulators/openbb_regulators/sec/sec_router.py
+++ b/openbb_platform/extensions/regulators/openbb_regulators/sec/sec_router.py
@@ -14,51 +14,94 @@ from openbb_core.app.router import Router
 router = Router(prefix="/sec")
 
 
-@router.command(model="CikMap")
+@router.command(
+    model="CikMap",
+    exclude_auto_examples=True,
+    examples=[
+        'obb.regulators.sec.cik_map(symbol="MSFT").results.cik',
+        "    0000789019",
+    ],
+)
 async def cik_map(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get the CIK number corresponding to a ticker symbol."""
+    """Map a ticker symbol to a CIK number."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="InstitutionsSearch")
+@router.command(
+    model="InstitutionsSearch",
+    exclude_auto_examples=True,
+    examples=[
+        'obb.regulators.sec.institutions_search(query="blackstone real estate").to_df()'
+    ],
+)
 async def institutions_search(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Look up institutions regulated by the SEC."""
+    """Search SEC-regulated institutions by name and return a list of results with CIK numbers."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="SchemaFiles")
+@router.command(
+    model="SchemaFiles",
+    exclude_auto_examples=True,
+    examples=[
+        "data = obb.regulators.sec.schema_files()",
+        "data.files[0]",
+        "    https://xbrl.fasb.org/us-gaap/",
+        "#### The directory structure can be navigated by constructing a URL from the 'results' list. ####",
+        "url = data.files[0]+data.files[-1]",
+        "#### The URL base will always be the 0 position in the list, feed  the URL back in as a parameter. ####",
+        "obb.regulators.sec.schema_files(url=url).results.files",
+        "    ['https://xbrl.fasb.org/us-gaap/2024/'",
+        "    'USGAAP2024FileList.xml'",
+        "    'dis/'",
+        "    'dqcrules/'",
+        "    'ebp/'",
+        "    'elts/'",
+        "    'entire/'",
+        "    'meta/'",
+        "    'stm/'",
+        "    'us-gaap-2024.zip']",
+    ],
+)
 async def schema_files(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get lists of SEC XML schema files by year."""
+    """A tool for navigating the directory of SEC XML schema files by year."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="SymbolMap")
+@router.command(
+    model="SymbolMap",
+    exclude_auto_examples=True,
+    examples=['obb.regulators.sec.symbol_map("0000789019").results.symbol', "    MSFT"],
+)
 async def symbol_map(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Get the ticker symbol corresponding to a company's CIK."""
+    """Map a CIK number to a ticker symbol, leading 0s can be omitted or included."""
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="RssLitigation")
+@router.command(
+    model="RssLitigation",
+    exclude_auto_examples=True,
+    examples=['obb.regulators.sec.rss_litigation().to_dict("records")[0]'],
+)
 async def rss_litigation(
     cc: CommandContext,
     provider_choices: ProviderChoices,
@@ -69,12 +112,18 @@ async def rss_litigation(
     return await OBBject.from_query(Query(**locals()))
 
 
-@router.command(model="SicSearch")
+@router.command(
+    model="SicSearch",
+    exclude_auto_examples=True,
+    examples=[
+        'obb.regulators.sec.sic_search("real estate investment trusts").results',
+    ],
+)
 async def sic_search(
     cc: CommandContext,
     provider_choices: ProviderChoices,
     standard_params: StandardParams,
     extra_params: ExtraParams,
 ) -> OBBject:
-    """Search for Industry Titles, Reporting Office, and SIC Codes."""
+    """Search for Industry Titles, Reporting Office, and SIC Codes. An empty query string returns all results."""
     return await OBBject.from_query(Query(**locals()))
diff --git a/openbb_platform/openbb/package/regulators_sec.py b/openbb_platform/openbb/package/regulators_sec.py
index 16928cc4b8e..8be04d1e0b8 100644
--- a/openbb_platform/openbb/package/regulators_sec.py
+++ b/openbb_platform/openbb/package/regulators_sec.py
@@ -32,7 +32,7 @@ class ROUTER_regulators_sec(Container):
         provider: Optional[Literal["sec"]] = None,
         **kwargs
     ) -> OBBject:
-        """Get the CIK number corresponding to a ticker symbol.
+        """Map a ticker symbol to a CIK number.
 
         Parameters
         ----------
@@ -65,7 +65,8 @@ class ROUTER_regulators_sec(Container):
         Example
         -------
         >>> from openbb import obb
-        >>> obb.regulators.sec.cik_map(symbol="AAPL")
+        >>> obb.regulators.sec.cik_map(symbol="MSFT").results.cik
+        >>>     0000789019
         """  # noqa: E501
 
         return self._run(
@@ -94,7 +95,7 @@ class ROUTER_regulators_sec(Container):
         provider: Optional[Literal["sec"]] = None,
         **kwargs
     ) -> OBBject:
-        """Look up institutions regulated by the SEC.
+        """Search SEC-regulated institutions by name and return a list of results with CIK numbers.
 
         Parameters
         ----------
@@ -131,7 +132,7 @@ class ROUTER_regulators_sec(Container):
         Example
         -------
         >>> from openbb import obb
-        >>> obb.regulators.sec.institutions_search(query="AAPL", use_cache=True)
+        >>> obb.regulators.sec.institutions_search(query="blackstone real estate").to_df()
         """  # noqa: E501
 
         return self._run(
@@ -191,7 +192,7 @@ class ROUTER_regulators_sec(Container):
         Example
         -------
         >>> from openbb import obb
-        >>> obb.regulators.sec.rss_litigation()
+        >>> obb.regulators.sec.rss_litigation().to_dict("records")[0]
         """  # noqa: E501
 
         return self._run(
@@ -218,7 +219,7 @@ class ROUTER_regulators_sec(Container):
         provider: Optional[Literal["sec"]] = None,
         **kwargs
     ) -> OBBject:
-        """Get lists of SEC XML schema files by year.
+        """A tool for navigating the directory of SEC XML schema files by year.
 
         Parameters
         ----------
@@ -255,7 +256,23 @@ class ROUTER_regulators_sec(Container):
         Example
         -------
         >>> from openbb import obb
-        >>> obb.regulators.sec.schema_files(query="AAPL", use_cache=True)
+        >>> data = obb.regulators.sec.schema_files()
+        >>> data.files[0]
+        >>>     https://xbrl.fasb.org/us-gaap/
+        >>> #### The directory structure can be navigated by constructing a URL from the 'results' list. ####
+        >>> url = data.files[0]+data.files[-1]
+        >>> #### The URL base will always be the 0 position in the list, feed  the URL back in as a parameter. ####
+        >>> obb.regulators.sec.schema_files(url=url).results.files
+        >>>     ['https://xbrl.fasb.org/us-gaap/2024/',
+        >>>     'USGAAP2024FileList.xml'
+        >>>     'dis/'
+        >>>     'dqcrules/'
+        >>>    'ebp/'
+        >>>    'elts/'
+        >>>    'entire/'
+        >>>    'meta/'
+        >>>    'stm/'
+        >>>    'us-gaap-2024.zip']
         """  # noqa: E501
 
         return self._run(
@@ -285,7 +302,7 @@ class ROUTER_regulators_sec(Container):
         provider: Optional[Literal["sec"]] = None,
         **kwargs
     ) -> OBBject:
-        """Search for Industry Titles, Reporting Office, and SIC Codes.
+        """Search for Industry Titles, Reporting Office, and SIC Codes. An empty query string returns all results.
 
         Parameters
         ----------
@@ -324,7 +341,7 @@ class ROUTER_regulators_sec(Container):
         Example
         -------
         >>> from openbb import obb
-        >>> obb.regulators.sec.sic_search(query="AAPL", use_cache=True)
+        >>> obb.regulators.sec.sic_search("real estate investment trusts").results
         """  # noqa: E501
 
         return self._run(
@@ -354,7 +371,7 @@ class ROUTER_regulators_sec(Container):
         provider: Optional[Literal["sec"]] = None,
         **kwargs
     ) -> OBBject:
-        """Get the ticker symbol corresponding to a company's CIK.
+        """Map a CIK number to a ticker symbol, leading 0s can be omitted or included.
 
         Parameters
         ----------
@@ -389,7 +406,8 @@ class ROUTER_regulators_sec(Container):
         Example
         -------
         >>> from openbb import obb
-        >>> obb.regulators.sec.symbol_map(query="AAPL", use_cache=True)
+        >>> obb.regulators.sec.symbol_map("0000789019").results.symbol
+        >>>     MSFT
         """  # noqa: E501
 
         return self._run(