Update documentation of the app.py

Dear Maintainers,

I hope this message finds you well. I wanted to inform you that I have recently added documentation to the codebase.

If you have any feedback or suggestions regarding the documentation or any other aspect of the codebase, please don't hesitate to reach out. Your input is always valued and appreciated.

Thank you for your attention to this matter.

Best regards,
Louis Brulé Naudet

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]