Auto Generate API Documentation (#2360)

* Started auto doc generation

* Created a markdown document

* Added test changed to md

* Created working version of new documentation

* Made requested changes

* Generate docs for all

Co-authored-by: minhhoang1023 <40023817+minhhoang1023@users.noreply.github.com>

docs/generate.py

@@ -0,0 +1,92 @@
+from typing import Callable, Any, Optional
+from inspect import signature
+import importlib
+import os
+
+from openbb_terminal.api import functions
+
+
+def all_functions() -> list[tuple[str, str, Callable[..., Any]]]:
+    """Uses the base api functions dictionary to get a list of all functions we have linked
+    in our API.
+
+    Returns
+    ----------
+    func_list: list[Tuple[str, str, Callable[..., Any]]]
+        A list of functions organized as (path_to_func, view/model, the_function)
+    """
+    func_list = []
+    for key, sub_dict in functions.items():
+        for sub_key, item_path in sub_dict.items():
+            full_path = item_path.split(".")
+            module_path = ".".join(full_path[:-1])
+            module = importlib.import_module(module_path)
+            target_function = getattr(module, full_path[-1])
+            func_list.append((key, sub_key, target_function))
+    return func_list
+
+
+def groupby(orig_list: list[Any], index: int) -> dict[Any, Any]:
+    """Groups a list of iterable by the index provided
+
+    Parameters
+    ----------
+    orig_list: list[Any]
+        A list of iterables
+    index: int
+        The index to groupby
+
+    Returns
+    ----------
+    grouped: dict[Any, Any]
+        Group information where keys are the groupby item and values are the iterables
+    """
+    grouped: dict[Any, Any] = {}
+    for item in orig_list:
+        if item[index] in grouped:
+            grouped[item[index]].append(item)
+        else:
+            grouped[item[index]] = [item]
+    return grouped
+
+
+def generate_documentation(
+    base: str, key: str, value: list[tuple[str, str, Callable[..., Any]]]
+):
+    models = list(filter(lambda x: x[1] == "model", value))
+    views = list(filter(lambda x: x[1] == "view", value))
+    model_type = Optional[tuple[str, str, Callable[..., Any]]]
+    model: model_type = models[0] if models else None
+    view: model_type = views[0] if views else None
+    for end in key.split("."):
+        base += f"/{end}"
+        if not os.path.isdir(base):
+            os.mkdir(base)
+    with open(f"{base}/_index.md", "w") as f:
+        f.write(f"# {key}\n\n")
+        if view:
+            f.write(
+                "To obtain charts, make sure to add `chart=True` as the last parameter\n\n"
+            )
+        if model:
+            f.write(f"## Get underlying data \n###{key}{signature(model[2])}\n\n")
+            m_docs = str(model[2].__doc__)[:-5]
+            f.write(f"{m_docs}\n")
+        if view:
+            if model:
+                f.write("\n")
+            v_docs = str(view[2].__doc__)[:-5]
+            temp = str(signature(view[2]))
+            # TODO: This breaks if there is a ')' inside the function arguments
+            idx = temp.find(")")
+            new_signature = temp[:idx] + ", chart=True" + temp[idx:]
+            f.write(f"## Getting charts \n###{key}{new_signature}\n\n")
+            f.write(f"{v_docs}\n")
+
+
+if __name__ == "__main__":
+    folder_path = os.path.realpath("./website/content/api")
+    funcs = all_functions()
+    grouped_funcs = groupby(funcs, 0)
+    for k, v in grouped_funcs.items():
+        generate_documentation(folder_path, k, v)

openbb_terminal/alternative/oss/github_view.py

@@ -128,7 +128,7 @@ def display_repo_summary(repo: str, export: str = "") -> None:
     repo : str
             Repository to display summary. Format: org/repo, e.g., openbb-finance/openbbterminal
     export : str
-    Export dataframe data to csv,json,xlsx file
+        Export dataframe data to csv,json,xlsx file
     """
     data = github_model.get_repo_summary(repo)
     if not data.empty:

openbb_terminal/cryptocurrency/defi/graph_model.py

@@ -13,6 +13,7 @@
 from openbb_terminal.decorators import log_start_end
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 UNI_URL = "https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2"
 

openbb_terminal/cryptocurrency/due_diligence/coinpaprika_model.py

@@ -14,6 +14,7 @@
 from openbb_terminal.rich_config import console
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 
 @log_start_end(log=logger)

openbb_terminal/cryptocurrency/due_diligence/glassnode_model.py

@@ -10,6 +10,7 @@
 from openbb_terminal.rich_config import console
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 api_url = "https://api.glassnode.com/v1/metrics/"
 

openbb_terminal/cryptocurrency/due_diligence/messari_model.py

@@ -25,6 +25,7 @@
 logger = logging.getLogger(__name__)
 
 INTERVALS_TIMESERIES = ["5m", "15m", "30m", "1h", "1d", "1w"]
+# pylint: disable=unsupported-assignment-operation
 
 
 @log_start_end(log=logger)

openbb_terminal/cryptocurrency/onchain/ethplorer_view.py

@@ -14,6 +14,7 @@
 from openbb_terminal.rich_config import console
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 
 @log_start_end(log=logger)

openbb_terminal/cryptocurrency/overview/pycoingecko_model.py

@@ -20,6 +20,7 @@
 from openbb_terminal.decorators import log_start_end
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 HOLD_COINS = ["ethereum", "bitcoin"]
 

openbb_terminal/economy/finviz_model.py

@@ -14,6 +14,7 @@
 from openbb_terminal.helper_funcs import get_user_agent
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 GROUPS = {
     "sector": "Sector",

openbb_terminal/forex/polygon_model.py

@@ -8,6 +8,8 @@
 from openbb_terminal.helper_funcs import get_user_agent
 from openbb_terminal.rich_config import console
 
+# pylint: disable=unsupported-assignment-operation
+
 
 def get_historical(
     fx_pair: str,

openbb_terminal/stocks/dark_pool_shorts/stockgrid_model.py

@@ -11,6 +11,7 @@
 from openbb_terminal.decorators import log_start_end
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 
 @log_start_end(log=logger)

openbb_terminal/stocks/options/nasdaq_model.py

@@ -14,6 +14,7 @@
 from openbb_terminal.stocks.options.op_helpers import get_dte_from_expiration as get_dte
 
 logger = logging.getLogger(__name__)
+# pylint: disable=unsupported-assignment-operation
 
 
 @log_start_end(log=logger)

openbb_terminal/stocks/stocks_helper.py

@@ -36,6 +36,7 @@
 
 # pylint: disable=no-member,too-many-branches,C0302,R0913
 # pylint: disable=inconsistent-return-statements
+# pylint: disable=unsupported-assignment-operation
 
 INTERVALS = [1, 5, 15, 30, 60]
 SOURCES = ["YahooFinance", "AlphaVantage", "IEXCloud", "EODHD"]

openbb_terminal/stocks/tradinghours/bursa_model.py

@@ -11,6 +11,7 @@
 from openbb_terminal.decorators import log_start_end
 
 logger = logging.getLogger(__name__)
+# pylint: disable=no-member
 
 
 @log_start_end(log=logger)

website/content/api/alt/covid/case_slopes/_index.md

@@ -0,0 +1,17 @@
+# alt.covid.case_slopes
+
+## Get underlying data 
+###alt.covid.case_slopes(days_back: int = 30, threshold: int = 10000) -> pandas.core.frame.DataFrame
+
+Load cases and find slope over period
+
+    Parameters
+    ----------
+    days_back: int
+        Number of historical days to consider
+    threshold: int
+        Threshold for total number of cases
+    Returns
+    -------
+    pd.DataFrame
+        Dataframe containing slopes

website/content/api/alt/covid/global_cases/_index.md

@@ -0,0 +1,16 @@
+# alt.covid.global_cases
+
+## Get underlying data 
+###alt.covid.global_cases(country: str) -> pandas.core.frame.DataFrame
+
+Get historical cases for given country
+
+    Parameters
+    ----------
+    country: str
+        Country to search for
+
+    Returns
+    -------
+    pd.DataFrame
+        Dataframe of historical cases

website/content/api/alt/covid/global_deaths/_index.md

@@ -0,0 +1,16 @@
+# alt.covid.global_deaths
+
+## Get underlying data 
+###alt.covid.global_deaths(country: str) -> pandas.core.frame.DataFrame
+
+Get historical deaths for given country
+
+    Parameters
+    ----------
+    country: str
+        Country to search for
+
+    Returns
+    -------
+    pd.DataFrame
+        Dataframe of historical deaths

website/content/api/alt/covid/ov/_index.md

@@ -0,0 +1,33 @@
+# alt.covid.ov
+
+To obtain charts, make sure to add `chart=True` as the last parameter
+
+## Get underlying data 
+###alt.covid.ov(country, limit: int = 100) -> pandas.core.frame.DataFrame
+
+Get historical cases and deaths by country
+
+    Parameters
+    ----------
+    country: str
+        Country to get data for
+    limit: int
+        Number of raw data to show
+
+## Getting charts 
+###alt.covid.ov(country, raw: bool = False, limit: int = 10, export: str = '', plot: bool = True, chart=True) -> None
+
+Show historical cases and deaths by country
+
+    Parameters
+    ----------
+    country: str
+        Country to get data for
+    raw: bool
+        Flag to display raw data
+    limit: int
+        Number of raw data to show
+    export: str
+        Format to export data
+    plot: bool
+        Flag to display historical plot

website/content/api/alt/covid/slopes/_index.md

@@ -0,0 +1,41 @@
+# alt.covid.slopes
+
+To obtain charts, make sure to add `chart=True` as the last parameter
+
+## Get underlying data 
+###alt.covid.slopes(days_back: int = 30, limit: int = 50, threshold: int = 10000, ascend: bool = False) -> pandas.core.frame.DataFrame
+
+Load cases and find slope over period
+
+    Parameters
+    ----------
+    days_back: int
+        Number of historical days to consider
+    limit: int
+        Number of rows to show
+    threshold: int
+        Threshold for total number of cases
+    ascend: bool
+        Flag to sort in ascending order
+    Returns
+    -------
+    pd.DataFrame
+        Dataframe containing slopes
+
+## Getting charts 
+###alt.covid.slopes(days_back: int = 30, limit: int = 10, threshold: int = 10000, ascend: bool = False, export: str = '', chart=True) -> None
+
+
+
+    Parameters
+    ----------
+    days_back: int
+        Number of historical days to get slope for
+    limit: int
+        Number to show in table
+    ascend: bool
+        Flag to sort in ascending order
+    threshold: int
+        Threshold for total cases over period
+    export : str
+        Format to export data

website/content/api/alt/covid/stat/_index.md

@@ -0,0 +1,37 @@
+# alt.covid.stat
+
+To obtain charts, make sure to add `chart=True` as the last parameter
+
+## Get underlying data 
+###alt.covid.stat(country, stat: str = 'cases', limit: int = 10) -> pandas.core.frame.DataFrame
+
+Show historical cases and deaths by country
+
+    Parameters
+    ----------
+    country: str
+        Country to get data for
+    stat: str
+        Statistic to get.  Either "cases", "deaths" or "rates"
+    limit: int
+        Number of raw data to show
+
+## Getting charts 
+###alt.covid.stat(country, stat: str = 'cases', raw: bool = False, limit: int = 10, export: str = '', plot: bool = True, chart=True) -> None
+
+Show historical cases and deaths by country
+
+    Parameters
+    ----------
+    country: str
+        Country to get data for
+    stat: str
+        Statistic to get.  Either "cases", "deaths" or "rates"
+    raw: bool
+        Flag to display raw data
+    limit: int
+        Number of raw data to show
+    export: str
+        Format to export data
+    plot : bool
+        Flag to plot data

website/content/api/alt/oss/_make_request/_index.md

@@ -0,0 +1,15 @@
+# alt.oss._make_request
+
+## Get underlying data 
+###alt.oss._make_request(url: str) -> Optional[bs4.BeautifulSoup]
+
+Helper method to scrap
+
+    Parameters
+    ----------
+    url : str
+        url to scrape
+
+    Returns
+    -------
+        BeautifulSoup object