Update documentation of the app.py

app.py

@@ -42,10 +42,76 @@ from src.tools.plots import (
 #enable_space_ci()
 
 def restart_space():
+    """
+    Restarts a Space instance specified by its repository ID.
+
+    This function is used to restart a Space instance within the Hugging Face platform.
+    It requires the repository ID and a valid API token for authentication.
+
+    Parameters as env variables
+    ---------------------------
+    repo_id : str
+        The ID of the repository associated with the Space instance to be restarted.
+
+    token : str
+        A valid API token with the necessary permissions to restart the Space.
+
+    Returns
+    -------
+    None
+        This function does not return any value. It simply restarts the specified Space instance.
+
+    Example
+    -------
+    >>> restart_space(repo_id="example_repo_id", token="example_token")
+    """
     API.restart_space(repo_id=REPO_ID, token=H4_TOKEN)
 
 
 def init_space():
+    """
+    Initializes the Hugging Face Space environment.
+
+    This function initializes the Hugging Face Space environment by performing the following steps:
+    1. Downloads evaluation requests, dynamic information, and evaluation results.
+    2. Processes the raw data into a leaderboard DataFrame.
+    3. Updates collections with the original DataFrame.
+    4. Creates a plot DataFrame for visualization.
+    5. Retrieves evaluation queue DataFrames.
+
+    Returns
+    -------
+    tuple
+        A tuple containing the following elements:
+        - leaderboard_df : pandas.DataFrame
+            DataFrame containing the leaderboard data.
+            
+        - original_df : pandas.DataFrame
+            Original DataFrame obtained from the evaluation results.
+            
+        - plot_df : pandas.DataFrame
+            DataFrame suitable for creating plots.
+            
+        - finished_eval_queue_df : pandas.DataFrame
+            DataFrame containing finished evaluation queue data.
+            
+        - running_eval_queue_df : pandas.DataFrame
+            DataFrame containing running evaluation queue data.
+            
+        - pending_eval_queue_df : pandas.DataFrame
+            DataFrame containing pending evaluation queue data.
+
+    Example
+    -------
+    >>> (
+    ...     leaderboard_df,
+    ...     original_df,
+    ...     plot_df,
+    ...     finished_eval_queue_df,
+    ...     running_eval_queue_df,
+    ...     pending_eval_queue_df,
+    ... ) = init_space()
+    """
     try:
         print(EVAL_REQUESTS_PATH)
         snapshot_download(
@@ -102,6 +168,51 @@ def update_table(
     hide_models: list,
     query: str,
 ):
+    """
+    Updates a table DataFrame based on specified criteria.
+
+    This function filters the input DataFrame based on specified criteria and returns a new DataFrame with selected columns.
+
+    Parameters
+    ----------
+    hidden_df : pandas.DataFrame
+        The DataFrame to be filtered and updated.
+
+    columns : list
+        List of column names to be included in the updated DataFrame.
+
+    type_query : list
+        List of types to filter models.
+
+    precision_query : str
+        Precision value to filter models.
+
+    size_query : list
+        List of sizes to filter models.
+
+    hide_models : list
+        List of models to be hidden.
+
+    query : str
+        Query string to filter rows in the DataFrame.
+
+    Returns
+    -------
+    updated_df : pandas.DataFrame
+        A DataFrame containing filtered and updated data based on the specified criteria.
+
+    Example
+    -------
+    >>> updated_df = update_table(
+    ...     hidden_df=original_df,
+    ...     columns=["Model", "Type", "Precision"],
+    ...     type_query=["type1", "type2"],
+    ...     precision_query="high",
+    ...     size_query=["large"],
+    ...     hide_models=["model1", "model2"],
+    ...     query="column1 > 0 and column2 == 'value'",
+    ... )
+    """
     filtered_df = filter_models(df=hidden_df, type_query=type_query, size_query=size_query, precision_query=precision_query, hide_models=hide_models)
     filtered_df = filter_queries(query, filtered_df)
     df = select_columns(filtered_df, columns)
@@ -109,15 +220,83 @@ def update_table(
 
 
 def load_query(request: gr.Request):  # triggered only once at startup => read query parameter if it exists
+    """
+    Loads a query parameter from a request object.
+
+    It returns the query parameter value for the "search_bar" component and for a hidden component that triggers a reload only if the value has changed.
+
+    Parameters
+    ----------
+    request : gr.Request
+        The request object containing query parameters.
+
+    Returns
+    -------
+    tuple
+        A tuple containing two identical query parameter values:
+        - query_search_bar : str
+            The query parameter value for the "search_bar" component.
+            
+        - query_hidden : str
+            The query parameter value for a hidden component that triggers a reload only if the value has changed.
+
+    Example
+    -------
+    >>> query_search_bar, query_hidden = load_query(request)
+    """
     query = request.query_params.get("query") or ""
     return query, query # return one for the "search_bar", one for a hidden component that triggers a reload only if value has changed
 
 
 def search_table(df: pd.DataFrame, query: str) -> pd.DataFrame:
+    """
+    Searches a DataFrame for rows containing a specified query.
+
+    This function filters the input DataFrame based on a specified query and returns a new DataFrame containing rows where the query matches any part of the specified column.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        The DataFrame to be searched.
+
+    query : str
+        The query string to search for within the DataFrame.
+
+    Returns
+    -------
+    filtered_df : pandas.DataFrame
+        A DataFrame containing rows where the query matches any part of the specified column.
+
+    Example
+    -------
+    >>> filtered_df = search_table(df=original_df, query="example_query")
+    """
     return df[(df[AutoEvalColumn.dummy.name].str.contains(query, case=False))]
 
 
 def select_columns(df: pd.DataFrame, columns: list) -> pd.DataFrame:
+    """
+    Selects specified columns from a DataFrame.
+
+    This function selects specified columns from the input DataFrame and returns a new DataFrame containing only those columns.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        The DataFrame from which columns are to be selected.
+
+    columns : list
+        List of column names to be selected from the DataFrame.
+
+    Returns
+    -------
+    filtered_df : pandas.DataFrame
+        A DataFrame containing only the specified columns.
+
+    Example
+    -------
+    >>> filtered_df = select_columns(df=original_df, columns=["column1", "column2", "column3"])
+    """
     always_here_cols = [c.name for c in fields(AutoEvalColumn) if c.never_hidden]
     dummy_col = [AutoEvalColumn.dummy.name]
         #AutoEvalColumn.model_type_symbol.name,
@@ -131,6 +310,31 @@ def select_columns(df: pd.DataFrame, columns: list) -> pd.DataFrame:
 
 def filter_queries(query: str, filtered_df: pd.DataFrame):
     """Added by Abishek"""
+    """
+    Filters DataFrame rows based on specified query strings.
+
+    This function filters the input DataFrame based on specified query strings and returns a new DataFrame containing rows that match any of the queries.
+
+    Parameters
+    ----------
+    query : str
+        The query string containing one or more search queries separated by semicolons (;).
+
+    filtered_df : pandas.DataFrame
+        The DataFrame to be filtered based on the queries.
+
+    Returns
+    -------
+    filtered_df : pandas.DataFrame
+        A DataFrame containing rows that match any of the specified queries.
+
+    Example
+    -------
+    >>> filtered_df = filter_queries(
+    ...     query="query1; query2; query3",
+    ...     filtered_df=original_df,
+    ... )
+    """
     final_df = []
     if query != "":
         queries = [q.strip() for q in query.split(";")]
@@ -152,6 +356,43 @@ def filter_queries(query: str, filtered_df: pd.DataFrame):
 def filter_models(
     df: pd.DataFrame, type_query: list, size_query: list, precision_query: list, hide_models: list
 ) -> pd.DataFrame:
+    """
+    Filters DataFrame rows based on specified criteria.
+
+    This function filters the input DataFrame based on specified criteria such as model type, size, precision, and models to hide.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        The DataFrame to be filtered.
+
+    type_query : list
+        List of tuples containing model types to include in the filtering. Each tuple consists of a model type abbreviation and its corresponding emoji.
+
+    size_query : list
+        List of size categories to include in the filtering.
+
+    precision_query : list
+        List of precision values to include in the filtering.
+
+    hide_models : list
+        List of model categories to hide from the DataFrame.
+
+    Returns
+    -------
+    filtered_df : pandas.DataFrame
+        A DataFrame containing rows that meet the specified filtering criteria.
+
+    Example
+    -------
+    >>> filtered_df = filter_models(
+    ...     df=original_df,
+    ...     type_query=[("Type1", "🔥"), ("Type2", "⭐")],
+    ...     size_query=["Large", "Medium"],
+    ...     precision_query=["High", "Medium"],
+    ...     hide_models=["Private or deleted", "Contains a merge/moerge", "MoE", "Flagged"],
+    ... )
+    """
     # Show all models
     if "Private or deleted" in hide_models:
         filtered_df = df[df[AutoEvalColumn.still_on_hub.name] == True]