docs: final google docs, add lint rules (marimo-team#3226)

mscolnick · web-flow · commit a77fe03f67d2 · 2024-12-18T19:04:33.000-05:00
Lint rules to enforce google docs: https://www.pydocstyle.org/en/stable/error_codes.html
diff --git a/marimo/_ast/app.py b/marimo/_ast/app.py
@@ -198,7 +198,7 @@ def cell(
         hide_code: bool = False,
         **kwargs: Any,
     ) -> Cell | Callable[[Callable[..., Any]], Cell]:
-        """A decorator to add a cell to the app
+        """A decorator to add a cell to the app.
 
         This decorator can be called with or without parentheses. Each of the
         following is valid:
@@ -218,9 +218,11 @@ def __(mo):
         ```
 
         Args:
-        - func: The decorated function
-        - disabled: Whether to disable the cell
-        - kwargs: For forward-compatibility with future arguments
+            func: The decorated function.
+            column: The column number to place this cell in.
+            disabled: Whether to disable the cell.
+            hide_code: Whether to hide the cell's code.
+            **kwargs: For forward-compatibility with future arguments.
         """
         del kwargs
 
diff --git a/marimo/_ast/cell.py b/marimo/_ast/cell.py
@@ -512,7 +512,7 @@ def add(mo, x, y):
             ```
 
         Args:
-            **kwargs (Any):
+            **refs (Any):
                 You may pass values for any of this cell's references as keyword
                 arguments. marimo will automatically compute values for any refs
                 that are not provided by executing the parent cells that compute
diff --git a/marimo/_output/data/data.py b/marimo/_output/data/data.py
@@ -31,7 +31,8 @@ def image(data: bytes, ext: str = "png") -> VirtualFile:
     """Create a virtual file from an image.
 
     Args:
-        data: Image data in bytes
+        data (bytes): Image data in bytes
+        ext (str): File extension
 
     Returns:
         A `VirtualFile` object.
@@ -45,7 +46,8 @@ def audio(data: bytes, ext: str = "wav") -> VirtualFile:
     """Create a virtual file from audio.
 
     Args:
-        data: Audio data in bytes
+        data (bytes): Audio data in bytes
+        ext (str): File extension
 
     Returns:
         A `VirtualFile` object.
diff --git a/marimo/_output/formatting.py b/marimo/_output/formatting.py
@@ -310,23 +310,18 @@ def mime_to_html(mimetype: KnownMimeType, data: Any) -> Html:
 
 @mddoc
 def plain(value: Any) -> Plain:
-    """
-    Wrap a value to indicate that it should be displayed
-    without any opinionated formatting.
-
-    This is the best way to opt out of marimo's
-    default dataframe rendering.
-
-    **Example.**
+    """Wrap a value to indicate that it should be displayed without any opinionated formatting.
 
-    ```python
-    df = data.cars()
-    mo.plain(df)
-    ```
+    This is the best way to opt out of marimo's default dataframe rendering.
 
-    **Args.**
+    Example:
+        ```python
+        df = data.cars()
+        mo.plain(df)
+        ```
 
-    - `value`: Any value
+    Args:
+        value: Any value
     """
     return Plain(value)
 
@@ -343,8 +338,7 @@ def __init__(self, child: Any):
 
 @mddoc
 def iframe(html: str, *, width: str = "100%", height: str = "400px") -> Html:
-    """
-    Embed an HTML string in an iframe.
+    """Embed an HTML string in an iframe.
 
     Scripts by default are not executed using `mo.as_html` or `mo.Html`,
     so if you have a script tag (written as `<script></script>`),
@@ -354,16 +348,16 @@ def iframe(html: str, *, width: str = "100%", height: str = "400px") -> Html:
     that may contain styles that could interfere with the rest of the
     page.
 
-    **Example.**
-
-    ```python
-    html = "<h1>Hello, world!</h1>"
-    mo.iframe(html)
-    ```
-
-    **Args.**
+    Example:
+        ```python
+        html = "<h1>Hello, world!</h1>"
+        mo.iframe(html)
+        ```
 
-    - `html`: An HTML string
+    Args:
+        html (str): An HTML string
+        width (str): The width of the iframe
+        height (str): The height of the iframe
     """
 
     return Html(
diff --git a/marimo/_plugins/stateless/download.py b/marimo/_plugins/stateless/download.py
@@ -28,13 +28,15 @@ def download(
     Show a download button for a url, bytes, or file-like object.
 
     Args:
-        data: The data to download. Can be a string (interpreted as
+        data (Union[str, bytes, io.BytesIO]): The data to download. Can be a string (interpreted as
             a URL), bytes, or a file opened in binary mode.
-        filename: The name of the file to download.
+        filename (str): The name of the file to download.
             If not provided, the name will be guessed from the data.
-        mimetype: The mimetype of the file to download, for example,
+        mimetype (str): The mimetype of the file to download, for example,
             (e.g. "text/csv", "image/png"). If not provided,
             the mimetype will be guessed from the filename.
+        disabled (bool): Whether to disable the download button.
+        label (str): The label of the download button.
 
     Returns:
         An `Html` object for a download button.
diff --git a/marimo/_plugins/stateless/nav_menu.py b/marimo/_plugins/stateless/nav_menu.py
@@ -26,6 +26,7 @@ def nav_menu(
         menu: a dictionary of tab names to tab content;
             the content can also be nested dictionaries (one level deep)
             strings are interpreted as markdown
+        orientation (Literal["horizontal", "vertical"]): The orientation of the menu.
 
     Returns:
         An `Html` object.
diff --git a/marimo/_plugins/ui/_core/ui_element.py b/marimo/_plugins/ui/_core/ui_element.py
@@ -354,61 +354,52 @@ def form(
     ) -> form_plugin[S, T]:
         """Create a submittable form out of this `UIElement`.
 
-        Use this method to create a form that gates the submission
-        of a `UIElement`s value until a submit button is clicked.
-
-        The value of the `form` is the value of the underlying
-        element the last time the form was submitted.
-
-        **Examples.**
-
-        Convert any `UIElement` into a form:
-
-        ```python
-        prompt = mo.ui.text_area().form()
-        ```
-
-        Combine with `HTML.batch` to create a form made out of multiple
-        `UIElements`:
-
-        ```python
-        form = (
-            mo.ui.md(
-                '''
-            **Enter your prompt.**
-
-            {prompt}
-
-            **Choose a random seed.**
+        Creates a form that gates submission of a `UIElement`'s value until a submit button is clicked.
+        The form's value is the value of the underlying element from the last submission.
+
+        Examples:
+            Convert any `UIElement` into a form:
+                ```python
+                prompt = mo.ui.text_area().form()
+                ```
+
+            Combine with `HTML.batch` to create a form made out of multiple `UIElements`:
+                ```python
+                form = (
+                    mo.ui.md(
+                        '''
+                    **Enter your prompt.**
+
+                    {prompt}
+
+                    **Choose a random seed.**
+
+                    {seed}
+                    '''
+                    )
+                    .batch(
+                        prompt=mo.ui.text_area(),
+                        seed=mo.ui.number(),
+                    )
+                    .form()
+                )
+                ```
 
-            {seed}
-            '''
-            )
-            .batch(
-                prompt=mo.ui.text_area(),
-                seed=mo.ui.number(),
-            )
-            .form()
-        )
-        ```
-
-        **Args.**
-
-        - `label`: A text label for the form.
-        - `bordered`: whether the form should have a border
-        - `loading`: whether the form should be in a loading state
-        - `submit_button_label`: the label of the submit button
-        - `submit_button_tooltip`: the tooltip of the submit button
-        - `submit_button_disabled`: whether the submit button should be
-          disabled
-        - `clear_on_submit`: whether the form should clear its contents after
-            submitting
-        - `show_clear_button`: whether the form should show a clear button
-        - `clear_button_label`: the label of the clear button
-        - `clear_button_tooltip`: the tooltip of the clear button
-        - `validate`: a function that takes the form's value and returns an
-            error message if the value is invalid,
-            or `None` if the value is valid
+        Args:
+            label: A text label for the form.
+            bordered: Whether the form should have a border.
+            loading: Whether the form should be in a loading state.
+            submit_button_label: The label of the submit button.
+            submit_button_tooltip: The tooltip of the submit button.
+            submit_button_disabled: Whether the submit button should be disabled.
+            clear_on_submit: Whether the form should clear its contents after submitting.
+            show_clear_button: Whether the form should show a clear button.
+            clear_button_label: The label of the clear button.
+            clear_button_tooltip: The tooltip of the clear button.
+            validate: A function that takes the form's value and returns an error message if invalid,
+                or `None` if valid.
+            on_change: A callback that takes the form's value and returns an error message if invalid,
+                or `None` if valid.
         """
         from marimo._plugins.ui._impl.input import form as form_plugin
 
diff --git a/marimo/_runtime/complete.py b/marimo/_runtime/complete.py
@@ -380,18 +380,17 @@ def complete(
     and more comprehensive, but can only be carried out when the kernel
     isn't executing or otherwise handling a request.
 
-    **Args.**
-
-    - `request`: the completion request
-    - `graph`: dataflow graph backing the marimo program
-    - `glbls`: global namespace
-    - `glbls_lock`: lock protecting the global namespace, for interpreter-based
-         completion
-    - `stream`: Stream through which to communicate completion results
-    - `docstrings_limit`: limit past which we won't attempt to fetch type hints
-          and docstrings
-    - `timeout`: timeout after which we'll stop fetching type hints/docstrings
-    - `prefer_interpreter_completion`: whether to prefer interpreter completion
+    Args:
+        request: The completion request
+        graph: Dataflow graph backing the marimo program
+        glbls: Global namespace
+        glbls_lock: Lock protecting the global namespace, for interpreter-based
+            completion
+        stream: Stream through which to communicate completion results
+        docstrings_limit: Limit past which we won't attempt to fetch type hints
+            and docstrings
+        timeout: Timeout after which we'll stop fetching type hints/docstrings
+        prefer_interpreter_completion: Whether to prefer interpreter completion
     """
     if not request.document.strip():
         _write_no_completions(stream, request.id)
diff --git a/marimo/_runtime/redirect_streams.py b/marimo/_runtime/redirect_streams.py
@@ -24,7 +24,7 @@ def forward_os_stream(stream_object: Stdout | Stderr, fd: int) -> None:
 def dup2newfd(fd: int) -> tuple[int, int, int]:
     """Create a pipe, with `fd` at the write end of it.
 
-    Returns
+    Returns:
     - duplicate (os.dup) of `fd`
     - read end of pipe
     - fd (which now points to the file referenced by the write end of the pipe)
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
@@ -921,7 +921,7 @@ def mutate_graph(
         absent-mindedly redefine an existing name when creating a new cell:
         such a mistake shouldn't invalidate the program state.
 
-        Returns
+        Returns:
         - set of cells that must be run to return kernel to consistent state
         """
         LOGGER.debug("Mutating graph.")
diff --git a/marimo/_save/hash.py b/marimo/_save/hash.py
diff --git a/marimo/_server/asgi.py b/marimo/_server/asgi.py
diff --git a/marimo/_utils/dataclass_to_openapi.py b/marimo/_utils/dataclass_to_openapi.py
diff --git a/marimo/_utils/parse_dataclass.py b/marimo/_utils/parse_dataclass.py
diff --git a/pyproject.toml b/pyproject.toml
