mljar · pplonski · Nov 7, 2023 · Nov 1, 2023 · Nov 1, 2023 · Nov 1, 2023
diff --git a/mercury/widgets/app.py b/mercury/widgets/app.py
@@ -6,10 +6,90 @@
 
 
 class App:
+    """
+    The App widget controls how the notebook is displayed within Mercury.
+
+    It provides configuration options for display features such as the title, 
+    description, code visibility, update behavior, and more, allowing for a 
+    customizable notebook presentation.
+
+    Parameters
+    ----------
+    title : str, default 'Title'
+        The title of the application. This is used in the home view and in the sidebar.
+        If an empty string is provided, the notebook filename will be displayed.
+
+    description : str, default 'Description'
+        A description of the application. This is used in the home view.
+        If an empty string is provided, no description will be displayed.
+
+    show_code : bool, default False
+        Set to True to display the notebook's code. The default is False, which means 
+        the code is hidden.
+
+    show_prompt : bool, default False
+        If True, the notebook prompt will be shown in the application. Requires 
+        `show_code` to be True as well. The default is False.
+
+    output : str, default 'app'
+        Determines the format of the notebook's output. The default is "app", 
+        meaning the notebook will be displayed as an interactive web application. 
+        If the notebook is detected to have presentation slides, the output format 
+        automatically changes to "slides".
+
+    schedule : str, default ''
+        A cron schedule expression that determines how frequently the notebook is 
+        run. The default is an empty string, meaning the notebook is not scheduled 
+        to run automatically. The `schedule` must be a valid cron expression, and 
+        its validity is checked upon notebook initialization.
+
+    notify : dict, default {}
+        A dictionary specifying notification settings. It determines the conditions 
+        under which notifications should be sent and who should receive them. 
+
+    continuous_update : bool, default True
+        If True (the default), the notebook is recomputed immediately after a widget 
+        value changes. Set to False to have updates occur after clicking a Run button.
+
+    static_notebook : bool, default False
+        When True, the notebook will not be recomputed on any widget change, making 
+        the notebook static. The default is False, which means the app presented in 
+        Mercury is interactive.
+
+    show_sidebar : bool, default True
+        Determines the visibility of the sidebar when the Mercury App is opened. 
+        By default, the sidebar is displayed, but it can be hidden with this 
+        parameter set to False.
+
+    full_screen : bool, default True
+        If True (the default), the notebook is displayed with full width. Set to 
+        False to limit notebook width to 1140px.
+
+    allow_download : bool, default True
+        If True (the default), a Download button is available to export results as 
+        a PDF or HTML file. Set to False to hide the Download button.
+
+    stop_on_error : bool, default False
+        If True, the notebook will stop execution when an error occurs in a cell. 
+        The default is False, meaning the notebook will execute all cells even with 
+        errors.
+
+    Examples
+    --------
+    Constructing Mercury App with `title` and `description` arguments.
+    >>> import mercury as mr
+    >>> app = mr.App(title="Mercury Title", description="Mercury description")
+
+    Constructing Mercury App to show notebook's code with `show_code` argument.
+    >>> app = mr.App(title="Mercury Title", 
+    ...              description="Mercury description", 
+    ...              show_code=True)
+    """
+
     def __init__(
         self,
-        title="",
-        description="",
+        title="Title",
+        description="Description",
         show_code=False,
         show_prompt=False,
         output="app",

diff --git a/mercury/widgets/button.py b/mercury/widgets/button.py
@@ -7,7 +7,54 @@
 
 
 class Button:
-    def __init__(self, label="", style="primary", disabled=False, hidden=False):
+    """
+    The Button class creates an interactive button widget in the Mercury UI sidebar.
+
+    The button is displayed below the code cell in a Jupyter Notebook or in the sidebar 
+    within Mercury.
+
+    Parameters
+    ----------
+    label : str, default 'Button'
+        The text displayed on the button. If an empty string is provided, the button 
+        will display no text.
+
+    style : str, default 'primary'
+        The style of the button, which changes its color. Valid styles include 
+        "primary", "success", "info", "warning", and "danger". If an invalid 
+        style is provided, it defaults to 'primary'.
+
+    disabled : bool, default False
+        If set to True, the button is disabled and cannot be clicked. The default 
+        is False, meaning the button is active.
+
+    hidden : bool, default False
+        If True, the button is not visible in 
10000
the sidebar. The default is False, 
+        meaning the button is visible.
+
+    Attributes
+    ----------
+    clicked : bool
+        A read-only property. Returns True if the button has been clicked since the 
+        last check, otherwise False. It resets to False after being read.
+
+    Examples
+    --------
+    Creating a Mercury Button.
+    >>> import mercury as mr
+    >>> button = mr.Button(label="Click Me")
+    >>> if button.clicked:              # after button clicked this will be true
+    >>>     print("Button clicked!")    # but it will be true only once!
+    >>> if button.clicked:              # second read will return false
+    >>>     print("It will not be printed!")
+
+    Creating a Mercury Button with a specific style.
+    >>> button = mr.Button(label="Click Me", style="success")
+    >>> if button.clicked:
+    >>>     print("Button clicked!")
+    """
+
+    def __init__(self, label="Button", style="primary", disabled=False, hidden=False):
         self.code_uid = WidgetsManager.get_code_uid("Button")
 
         if style not in ["primary", "success", "info", "warning", "danger", ""]:

diff --git a/mercury/widgets/checkbox.py b/mercury/widgets/checkbox.py
@@ -7,7 +7,66 @@
 
 
 class Checkbox:
-    def __init__(self, value=True, label="", url_key="", disabled=False, hidden=False):
+    """
+    The Checkbox class creates an interactive checkbox widget manifested as a 
+    toggle switch in the Mercury UI sidebar.
+
+    This widget allows users to toggle a selection (i.e., checked or unchecked) in 
+    the UI, which can then be used to control the logic in the application. This class 
+    also supports synchronizing the state of the checkbox with URL parameters for 
+    easy sharing.
+
+    Parameters
+    ----------
+    value : bool, default True
+        The initial state of the checkbox. If True, the checkbox is checked; if False, 
+        it's unchecked.
+
+    label : str, default 'Checkbox'
+        The text label displayed alongside the checkbox. If an empty string 
+        is provided, the checkbox will display no text.
+
+    url_key : str, default ''
+        If provided, this allows the checkbox's state to be synchronized with a URL 
+        parameter. The state of the checkbox can then be set and shared via the URL.
+
+    disabled : bool, default False
+        If True, the checkbox is rendered inactive in the UI and cannot be interacted 
+        with.
+
+    hidden : bool, default False
+        If True, the checkbox is not visible in the sidebar. The default is False, 
+        meaning the checkbox is visible.
+
+    Attributes
+    ----------
+    value : bool
+        A property that can be set or retrieved to change or get the checkbox's 
+        current state.
+
+    Examples
+    --------
+    Creating a Checkbox with a label, and checking its state.
+    >>> import mercury as mr
+    >>> my_flag = mr.Checkbox(value=True, label="Switch me")
+    >>> if my_flag.value:
+    >>>     print("Checkbox is ON")
+    >>> else:
+    >>>     print("Checkbox is OFF")
+
+    Creating a Checkbox with a URL key, which allows its state to be shared via 
+    the URL. This feature is useful for sharing the current state of the application 
+    with others by just sharing the URL.
+    >>> my_flag = mr.Checkbox(value=True, label="Switch me", url_key="flag")
+    >>> # The state of the checkbox can now be reflected in the URL.
+        >>> # For instance, if the checkbox is checked, and you click the 'Share' button 
+    >>> # in the Mercury sidebar, it will generate a URL like: 
+    >>> # https://your-server-address.com/app/notebook-name?flag=true
+    >>> # The '?flag=true' at the end of the URL indicates that the checkbox is checked.
+    >>> print(my_flag.value)  # Prints: True
+    """
+
+    def __init__(self, value=True, label="Checkbox", url_key="", disabled=False, hidden=False):
         self.code_uid = WidgetsManager.get_code_uid("Checkbox", key=url_key)
         self.url_key = url_key
         self.hidden = hidden

diff --git a/mercury/widgets/file.py b/mercury/widgets/file.py
@@ -11,6 +11,62 @@
 
 
 class File:
+    """
+    The File class provides an interface for uploading and reading files within 
+    the Mercury UI sidebar.
+
+    Files can be accessed as binary objects or read from a temporary file path. 
+    The File class allows for file interactions such as uploading, retrieving the 
+    file name, and reading file content in binary format or from the file path.
+
+    Parameters
+    ----------
+    label : str, default 'File upload'
+        The label of the file upload widget displayed in the UI. If an empty string 
+        is provided, it will display no text.
+
+    max_file_size : str, default '100MB'
+        Specifies the maximum file size allowed for upload. The size should be a 
+        string representing the limit in bytes, KB, MB, or GB (e.g., '100MB', '1GB').
+
+    disabled : bool, default False
+        Determines whether the file upload widget is disabled. If True, the widget 
+        is displayed but cannot be interacted with.
+
+    hidden : bool, default False
+        Controls the visibility of the file upload widget in the sidebar. If True, 
+        the widget will not be visible.
+
+    Attributes
+    ----------
+    value : bytes
+        The content of the uploaded file in binary format. If no file is uploaded, 
+        returns None.
+
+    filename : str
+        The name of the uploaded file. If no file is uploaded, returns None.
+
+    filepath : str
+        The path to the temporary file stored on the server. If no file is uploaded, 
+        returns None.
+
+    Examples
+    --------
+    Uploading a file and reading its content.
+    >>> import mercury as mr
+    >>> my_file = mr.File(label="File upload", max_file_size="100MB")
+    >>> # Only if a file is uploaded using the Mercury UI
+    >>> if my_file.filepath:
+    >>>     print(f"Uploaded file path: {my_file.filepath}")
+    >>>     with open(my_file.filepath, "r") as fin:
+    >>>         print(fin.read())
+    >>>     print(f"Thanks for uploading {my_file.filename}")
+
+    Retrieving file content in binary format.
+    >>> # 'binary_content' is a bytes object containing the file data
+    >>> binary_content = my_file.value
+    """
+
     def __init__(
         self, label="File upload", max_file_size="100MB", disabled=False, hidden=False
     ):

diff --git a/mercury/widgets/multiselect.py b/mercury/widgets/multiselect.py
@@ -7,10 +7,83 @@
 
 
 class MultiSelect:
+    """
+    The MultiSelect class introduces a multi-selection widget in the Mercury UI sidebar, 
+    allowing users to interactively choose multiple options from a predefined list.
+
+    Displayed as a dropdown menu, this widget permits users to select 
+    multiple choices from a given collection. Each choice is defined as a 
+    string, and the entire set of options is customizable. The selected values 
+    can be accessed programmatically, catering for dynamic reactions to user 
+    input within Mercury applications.
+
+    Parameters
+    ----------
+    value : list of str, default []
+        The initial selection(s) in the list. If not provided and the choices list 
+        is non-empty, defaults to the first item in the choices list. Defaults to 
+        an empty list.
+
+    choices : list of str, default []
+        The list of available options for users to select from. Defaults to an 
+        empty list.
+
+    label : str, default 'MultiSelect'
+        The label displayed next to the multi-selection widget. If an empty string 
+        is provided, it will display no text.
+
+    url_key : str, default ''
+        When set, this allows the widget's selections to be influenced by URL parameters, 
+        enabling the sharing of the widget's state via the URL. Defaults to an 
+        empty string.
+
+    disabled : bool, default False
+        If True, the list is displayed in the UI but is inactive, 
+        preventing user interactions. Defaults to False.
+
+    hidden : bool, default False
+        If set to True, the widget will not be displayed in the UI. Defaults to False.
+
+    Attributes
+    ----------
+    value : list of str
+        Retrieves the currently selected values from the list.
+
+    Examples
+    --------
+    Creating a MultiSelect widget with a set of options.
+    >>> import mercury as mr
+    >>> my_selections = mr.MultiSelect(value=["Option2"],
+    ...                                choices=["Option1", "Option2", "Option3"], 
+    ...                                label="Select options")
+    >>> # Prints: "Current selections: ['Option2']"
+    >>> print(f"Current selections: {my_selections.value}")
+
+    The first item in the `choices` list will be selected by default if `value` 
+    is not specified. The current selections can be obtained programmatically, 
+    useful for tailoring application behavior based on user choices.
+
+    Creating a MultiSelect widget with a URL key facilitates the current selections 
+    to be captured in the URL. This feature is especially useful for sharing the 
+    present state of the application with others through a URL.
+    >>> my_options = mr.MultiSelect(value=["Option2"], 
+    ...                             choices=["Option1", "Option2", "Option3"], 
+    ...                             label="Pick options", 
+    ...                             url_key="options")
+    >>> # If "Option2" and "Option3" are selected and you hit the 'Share' button 
+    >>> # in the Mercury sidebar, a URL similar to this might be produced: 
+    >>> # https://your-server-address.com/app/notebook-name?options=Option2,Option3
+    >>> # The '?options=Option2,Option3' at the end indicates that both "Option2" 
+    >>> # and "Option3" are selected.
+    >>> # Prints: "['Option1']" if no values are set in the URL, or the 
+    >>> # corresponding options reflected in the "options" URL parameter.
+    >>> print(my_options.value)
+    """
+
     def __init__(
-        self, value=[], choices=[], label="", url_key="", disabled=False, hidden=False
+        self, value=[], choices=[], label="MultiSelect", url_key="", disabled=False, hidden=False
     ):
-        if value is None and len(choices) > 1:
+        if not value and len(choices) > 1:
             value = [choices[0]]
 
         self.code_uid = WidgetsManager.get_code_uid("MultiSelect", key=url_key)