From ac8bbfb822f3e0b2ce7ee9e52e40345227173431 Mon Sep 17 00:00:00 2001
From: Xuan Ronaldo <xuanronaldo@qq.com>
Date: Fri, 13 Dec 2024 19:31:21 +0800
Subject: [PATCH] docs: update BaseFigure documentation

- Move name and title from required attributes to required methods
- Clarify @property decorator requirement for name and title methods
- Keep consistent documentation structure in both README and README_EN
---
 README.md                               | 23 +++++++++++++++++------
 README_EN.md                            | 23 +++++++++++++++++------
 examples/custom/custom_figure.py        |  9 +++++++--
 src/positionbt/visualization/base.py    | 12 ++++++++++--
 src/positionbt/visualization/figures.py | 18 ++++++++++++++----
 5 files changed, 65 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 03454e1..04e51ff 100644
--- a/README.md
+++ b/README.md
@@ -195,8 +195,13 @@ from positionbt import (
 class DrawdownFigure(BaseFigure):
     """Drawdown visualization figure"""
 
-    name = "drawdown"  # Unique identifier for the figure
-    title = "Strategy Drawdown"  # Display title for the figure
+    @property
+    def name(self) -> str:
+        return "drawdown"
+
+    @property
+    def title(self) -> str:
+        return "Strategy Drawdown"
 
     def create(self) -> go.Figure:
         """Create drawdown figure
@@ -378,13 +383,19 @@ BacktestVisualizer(
 #### BaseFigure
 可视化图表的基类，用于自定义新的图表类型。
 
-**必须实现的属性：**
-- `name`: 图表唯一标识符
-- `title`: 图表显示标题
-
 **必须实现的方法：**
+- `name(self) -> str`: 返回图表唯一标识符（需使用 @property 装饰器）
+- `title(self) -> str`: 返回图表显示标题（需使用 @property 装饰器）
 - `create(self) -> go.Figure`: 创建并返回 Plotly 图表对象
 
+**初始化参数：**
+- `results`: BacktestResult 对象，包含回测结果数据
+
+**可用属性：**
+- `results`: 回测结果对象
+- `funding_curve`: 净值曲线数据
+- `_fig`: 基础图表对象（包含默认布局设置）
+
 ### 注册器
 
 #### indicator_registry
diff --git a/README_EN.md b/README_EN.md
index 54b3000..03e4eb9 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -193,8 +193,13 @@ from positionbt import (
 class DrawdownFigure(BaseFigure):
     """Drawdown visualization figure"""
 
-    name = "drawdown"  # Unique identifier for the figure
-    title = "Strategy Drawdown"  # Display title for the figure
+        @property
+    def name(self) -> str:
+        return "drawdown"
+
+    @property
+    def title(self) -> str:
+        return "Strategy Drawdown"
 
     def create(self) -> go.Figure:
         """Create drawdown figure
@@ -375,13 +380,19 @@ Base class for indicator calculation, used for custom performance indicators.
 #### BaseFigure
 Base class for visualization charts, used for custom chart types.
 
-**Required Attributes:**
-- `name`: Unique chart identifier
-- `title`: Chart display title
-
 **Required Methods:**
+- `name(self) -> str`: Return chart unique identifier (requires @property decorator)
+- `title(self) -> str`: Return chart display title (requires @property decorator)
 - `create(self) -> go.Figure`: Create and return Plotly figure object
 
+**Initialization Parameters:**
+- `results`: BacktestResult object containing backtest data
+
+**Available Attributes:**
+- `results`: Backtest result object
+- `funding_curve`: NAV curve data
+- `_fig`: Base figure object (with default layout settings)
+
 ### Registries
 
 #### indicator_registry
diff --git a/examples/custom/custom_figure.py b/examples/custom/custom_figure.py
index de043e1..77a5ce1 100644
--- a/examples/custom/custom_figure.py
+++ b/examples/custom/custom_figure.py
@@ -13,8 +13,13 @@
 class DrawdownFigure(BaseFigure):
     """Drawdown visualization figure"""
 
-    name = "drawdown"  # Unique identifier for the figure
-    title = "Strategy Drawdown"  # Display title for the figure
+    @property
+    def name(self) -> str:
+        return "drawdown"
+
+    @property
+    def title(self) -> str:
+        return "Strategy Drawdown"
 
     def create(self) -> go.Figure:
         """Create drawdown figure
diff --git a/src/positionbt/visualization/base.py b/src/positionbt/visualization/base.py
index 9635803..f08e3d5 100644
--- a/src/positionbt/visualization/base.py
+++ b/src/positionbt/visualization/base.py
@@ -8,8 +8,15 @@
 class BaseFigure(ABC):
     """Base class for visualization figures"""
 
-    name: str = ""  # Unique identifier for the figure
-    title: str = ""  # Display title for the figure
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def title(self) -> str:
+        pass
 
     def __init__(self, results: BacktestResult):
         """Initialize base figure
@@ -45,6 +52,7 @@ def _create_base_figure(self) -> go.Figure:
         fig = go.Figure()
         fig.update_layout(
             title=self.title,
+            template="plotly_white",
             showlegend=True,
             hovermode="x unified",
             plot_bgcolor="white",
diff --git a/src/positionbt/visualization/figures.py b/src/positionbt/visualization/figures.py
index 1970dd9..ee76d9d 100644
--- a/src/positionbt/visualization/figures.py
+++ b/src/positionbt/visualization/figures.py
@@ -7,8 +7,13 @@
 class FundingCurveFigure(BaseFigure):
     """Funding curve visualization figure"""
 
-    name = "funding_curve"  # Unique identifier for the figure
-    title = "Funding Curve"  # Display title for the figure
+    @property
+    def name(self) -> str:
+        return "funding_curve"
+
+    @property
+    def title(self) -> str:
+        return "Funding Curve"
 
     def create(self) -> go.Figure:
         """Create funding curve figure
@@ -107,8 +112,13 @@ def _add_max_drawdown_visualization(
 class MonthlyReturnsFigure(BaseFigure):
     """Monthly returns distribution figure"""
 
-    name = "monthly_returns"  # Unique identifier for the figure
-    title = "Monthly Returns Distribution"  # Display title for the figure
+    @property
+    def name(self) -> str:
+        return "monthly_returns"
+
+    @property
+    def title(self) -> str:
+        return "Monthly Returns Distribution"
 
     def create(self) -> go.Figure:
         """Create monthly returns distribution figure