Fix docstring formatting for custom component baseclasses

holoviz · Jan 23, 2025 · 0866c44 · 0866c44
1 parent f40575b
commit 0866c44
Showing 1 changed file with 111 additions and 101 deletions.
diff --git a/panel/custom.py b/panel/custom.py
@@ -61,30 +61,32 @@ class PyComponent(Viewable, Layoutable):
 
     Reference: https://panel.holoviz.org/reference/custom_components/PyComponent.html
 
-    ```python
-    import panel as pn
-    import param
+    :Example:
 
-    pn.extension()
+    .. code-block:: python
 
-    class CounterButton(pn.custom.PyComponent, pn.widgets.WidgetBase):
+        import panel as pn
+        import param
 
-        value = param.Integer(default=0)
+        pn.extension()
 
-        def __panel__(self):
-            return pn.widgets.Button(
-                name=self._button_name, on_click=self._on_click
-            )
+        class CounterButton(pn.custom.PyComponent, pn.widgets.WidgetBase):
+
+            value = param.Integer(default=0)
+
+            def __panel__(self):
+                return pn.widgets.Button(
+                    name=self._button_name, on_click=self._on_click
+                )
 
-        def _on_click(self, event):
-            self.value += 1
+            def _on_click(self, event):
+                self.value += 1
 
-        @param.depends("value")
-        def _button_name(self):
-            return f"count is {self.value}"
+            @param.depends("value")
+            def _button_name(self):
+                return f"count is {self.value}"
 
-    CounterButton().servable()
-    ```
+        CounterButton().servable()
     '''
 
     def __init__(self, **params):
@@ -186,32 +188,34 @@ class ReactiveESM(ReactiveCustomBase, metaclass=ReactiveESMMetaclass):
     variable. Use this to define a `render` function as shown in the
     example below.
 
-    ```python
-    import panel as pn
-    import param
+    :Example:
 
-    pn.extension()
+    .. code-block:: python
 
-    class CounterButton(pn.custom.ReactiveESM):
+        import panel as pn
+        import param
 
-        value = param.Integer()
+        pn.extension()
 
-        _esm = """
-        export function render({ model }) {
-            let btn = document.createElement("button");
-            btn.innerHTML = `count is ${model.value}`;
-            btn.addEventListener("click", () => {
-                model.value += 1
-            });
-            model.on('value', () => {
-                btn.innerHTML = `count is ${model.value}`;
-            })
-            return btn
-        }
-        """
+        class CounterButton(pn.custom.ReactiveESM):
 
-    CounterButton().servable()
-    ```
+            value = param.Integer()
+
+            _esm = """
+            export function render({ model }) {
+                let btn = document.createElement("button");
+                btn.innerHTML = `count is ${model.value}`;
+                btn.addEventListener("click", () => {
+                    model.value += 1
+                });
+                model.on('value', () => {
+                    btn.innerHTML = `count is ${model.value}`;
+                })
+                return btn
+            }
+            """
+
+        CounterButton().servable()
     '''
 
     _bokeh_model = _BkReactiveESM
@@ -595,32 +599,34 @@ class JSComponent(ReactiveESM):
 
     Reference: https://panel.holoviz.org/reference/custom_components/JSComponent.html
 
-    ```python
-    import panel as pn
-    import param
+    :Example:
 
-    pn.extension()
+    .. code-block:: python
 
-    class CounterButton(pn.custom.JSComponent):
+        import panel as pn
+        import param
 
-        value = param.Integer()
+        pn.extension()
 
-        _esm = """
-        export function render({ model }) {
-            let btn = document.createElement("button");
-            btn.innerHTML = `count is ${model.value}`;
-            btn.addEventListener("click", () => {
-                model.value += 1
-            });
-            model.on('value', () => {
-                btn.innerHTML = `count is ${model.value}`;
-            })
-            return btn
-        }
-        """
+        class CounterButton(pn.custom.JSComponent):
 
-    CounterButton().servable()
-    ```
+            value = param.Integer()
+
+            _esm = """
+            export function render({ model }) {
+                let btn = document.createElement("button");
+                btn.innerHTML = `count is ${model.value}`;
+                btn.addEventListener("click", () => {
+                    model.value += 1
+                });
+                model.on('value', () => {
+                    btn.innerHTML = `count is ${model.value}`;
+                })
+                return btn
+            }
+            """
+
+        CounterButton().servable()
     '''
 
     __abstract = True
@@ -639,27 +645,29 @@ class ReactComponent(ReactiveESM):
 
     Reference: https://panel.holoviz.org/reference/custom_components/ReactComponent.html
 
-    ```python
-    import panel as pn
-    import param
+    :Example:
 
-    class CounterButton(pn.custom.ReactComponent):
+    .. code-block:: python
 
-        value = param.Integer()
+        import panel as pn
+        import param
 
-        _esm = """
-        export function render({model}) {
-        const [value, setValue] = model.useState("value");
-        return (
-            <button onClick={e => setValue(value+1)}>
-            count is {value}
-            </button>
-        )
-        }
-        """
+        class CounterButton(pn.custom.ReactComponent):
 
-    CounterButton().servable()
-    ```
+            value = param.Integer()
+
+            _esm = """
+            export function render({model}) {
+            const [value, setValue] = model.useState("value");
+            return (
+                <button onClick={e => setValue(value+1)}>
+                count is {value}
+                </button>
+            )
+            }
+            """
+
+        CounterButton().servable()
     '''
 
     __abstract = True
@@ -733,33 +741,35 @@ class AnyWidgetComponent(ReactComponent):
 
     Reference: https://panel.holoviz.org/reference/custom_components/AnyWidgetComponent.html
 
-    ```python
-    import param
-    import panel as pn
-
-    pn.extension()
-
-    class CounterWidget(pn.custom.AnyWidgetComponent):
-        _esm = """
-        function render({ model, el }) {
-        let count = () => model.get("value");
-        let btn = document.createElement("button");
-        btn.innerHTML = `count is ${count()}`;
-        btn.addEventListener("click", () => {
-            model.set("value", count() + 1);
-            model.save_changes();
-        });
-        model.on("change:value", () => {
+    :Example:
+
+    .. code-block:: python
+
+        import param
+        import panel as pn
+
+        pn.extension()
+
+        class CounterWidget(pn.custom.AnyWidgetComponent):
+            _esm = """
+            function render({ model, el }) {
+            let count = () => model.get("value");
+            let btn = document.createElement("button");
             btn.innerHTML = `count is ${count()}`;
-        });
-        el.appendChild(btn);
-        }
-        export default { render };
-        """
-        value = param.Integer()
+            btn.addEventListener("click", () => {
+                model.set("value", count() + 1);
+                model.save_changes();
+            });
+            model.on("change:value", () => {
+                btn.innerHTML = `count is ${count()}`;
+            });
+            el.appendChild(btn);
+            }
+            export default { render };
+            """
+            value = param.Integer()
 
-    CounterWidget().servable()
-    ```
+        CounterWidget().servable()
     '''
 
     __abstract = True