From 863655b391424bc23bf7fc50faaae28ef213c4a6 Mon Sep 17 00:00:00 2001
From: Akshat Jawne <69530774+AkshatJawne@users.noreply.github.com>
Date: Wed, 2 Oct 2024 16:36:12 -0400
Subject: [PATCH] docs: ui.heading (#908)

Closes #833
---
 plugins/ui/docs/components/heading.md         | 70 +++++++++++++++++++
 plugins/ui/docs/sidebar.json                  |  4 ++
 .../ui/src/deephaven/ui/components/heading.py |  4 ++
 3 files changed, 78 insertions(+)
 create mode 100644 plugins/ui/docs/components/heading.md

diff --git a/plugins/ui/docs/components/heading.md b/plugins/ui/docs/components/heading.md
new file mode 100644
index 000000000..75c4c3575
--- /dev/null
+++ b/plugins/ui/docs/components/heading.md
@@ -0,0 +1,70 @@
+# Heading
+
+The Heading component is used to create different levels of headings.
+
+By default, it creates a level 3 (`<h3>`) heading.
+
+## Example
+
+```python
+from deephaven import ui
+
+my_heading_basic = ui.heading("Hello world")
+```
+
+## UI recommendations
+
+Consider using a [`text`](./text.md) component if the content does not require a specific heading level or semantic importance, such as for paragraphs or inline text.
+
+
+## Content
+
+The heading component represents a header that inherits styling from its parent container.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def ui_heading_content_examples():
+    return [
+        ui.heading("Heading 1", level=1),
+        ui.heading("Heading 2", level=2),
+        ui.heading("Heading 3", level=3),
+        ui.heading("Heading 4", level=4),
+        ui.heading("Heading 5", level=5),
+        ui.heading("Heading 6", level=6),
+        ui.time_field(
+            label="Sample Label",
+            contextual_help=ui.contextual_help(ui.heading("Content tips")),
+        ),
+    ]
+
+
+my_heading_content_examples = ui_heading_content_examples()
+```
+
+
+## Color
+
+The color prop sets the text color for the heading component.
+
+```python
+from deephaven import ui
+
+
+my_heading_color_example = ui.flex(
+    ui.heading("Faded heading", color="gray-500"),
+    ui.heading("Negative heading", color="negative"),
+    ui.heading("Positive heading", color="positive"),
+    ui.heading("Hex color", color="#FA8072"),
+    ui.heading("Nested ", ui.text("example", color="green"), "!"),
+    direction="column",
+)
+```
+
+## API Reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.ui.heading
+```
\ No newline at end of file
diff --git a/plugins/ui/docs/sidebar.json b/plugins/ui/docs/sidebar.json
index 43422208b..892d7394c 100644
--- a/plugins/ui/docs/sidebar.json
+++ b/plugins/ui/docs/sidebar.json
@@ -49,6 +49,10 @@
             "label": "date_range_picker",
             "path": "components/date_range_picker.md"
           },
+          {
+            "label": "heading",
+            "path": "components/heading.md"
+          },
           {
             "label": "illustrated_message",
             "path": "components/illustrated_message.md"
diff --git a/plugins/ui/src/deephaven/ui/components/heading.py b/plugins/ui/src/deephaven/ui/components/heading.py
index 3f770694d..947efe6f2 100644
--- a/plugins/ui/src/deephaven/ui/components/heading.py
+++ b/plugins/ui/src/deephaven/ui/components/heading.py
@@ -107,6 +107,10 @@ def heading(
         UNSAFE_class_name: A CSS class to apply to the element.
         UNSAFE_style: A CSS style to apply to the element.
         key: A unique identifier used by React to render elements in a list.
+
+    Returns:
+        The rendered heading element.
+
     """
     return component_element(
         "Heading",