✨ Create Base Plotly Schema

docs/conf.py

@@ -4,6 +4,14 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import nltk
+
+# Make sure stopwords are available for autodoc
+try:
+    nltk.data.find("corpora/stopwords")
+except LookupError:
+    nltk.download("stopwords")
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -27,7 +35,6 @@
 
 
 # -- General configuration ---------------------------------------------------
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -40,6 +47,7 @@
     "sphinx_new_tab_link",
     "myst_nb",
     "sphinx_copybutton",
+    "sphinxcontrib.autodoc_pydantic",
 ]
 
 #  https://myst-nb.readthedocs.io/en/latest/computation/execute.html
@@ -81,7 +89,6 @@
     "conf.py",
 ]
 
-
 # Intersphinx options
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
@@ -93,6 +100,30 @@
     "numpy": ("https://numpy.org/doc/stable/", None),
 }
 
+# Options for the autodoc_pydantic extension
+autodoc_pydantic_field_show_default = True
+autodoc_pydantic_field_show_constraints = True
+autodoc_pydantic_field_list_validators = True
+autodoc_pydantic_model_signature_prefix = "class"
+autodoc_pydantic_field_signature_prefix = "attribute"
+autodoc_pydantic_field_show_required = True
+autodoc_pydantic_field_show_optional = True
+autodoc_pydantic_field_show_default = True
+autodoc_pydantic_field_doc_policy = "description"
+autodoc_pydantic_model_member_order = "bysource"
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_model_show_field_summary = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_validator_summary = False
+autodoc_pydantic_model_hide_paramlist = False
+autodoc_pydantic_field_list_validators = False
+
+# Options for the autodoc extension
+autodoc_default_options = {
+    "inherited-members": "BaseModel",
+    "show-inheritance": True,
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

pyproject.toml

@@ -53,6 +53,7 @@ docs = [
   "sphinx-new-tab-link!=0.2.2",
   "jupytext",
   "sphinx-copybutton",
+  "autodoc_pydantic",
 ]
 dev = [
   "black",

src/vuecore/plots/basic/bar.py

@@ -5,8 +5,10 @@
 from vuecore import EngineType
 from vuecore.engines import get_builder, get_saver
 from vuecore.schemas.basic.bar import BarConfig
+from vuecore.utils.docs_utils import document_pydant_params
 
 
+@document_pydant_params(BarConfig)
 def create_bar_plot(
     data: pd.DataFrame,
     engine: EngineType = EngineType.PLOTLY,
@@ -34,11 +36,6 @@ def create_bar_plot(
         The file format is automatically inferred from the file extension
         (e.g., '.html', '.png', '.jpeg', '.svg'). Defaults to None, meaning
         the plot will not be saved.
-    **kwargs
-        Keyword arguments for plot configuration. These arguments are
-        validated against the `BarConfig` Pydantic model. Refer to
-        `vuecore.schemas.basic.bar.BarConfig` for all available
-        options and their descriptions.
 
     Returns
     -------

src/vuecore/plots/basic/box.py

@@ -5,8 +5,10 @@
 from vuecore import EngineType
 from vuecore.engines import get_builder, get_saver
 from vuecore.schemas.basic.box import BoxConfig
+from vuecore.utils.docs_utils import document_pydant_params
 
 
+@document_pydant_params(BoxConfig)
 def create_box_plot(
     data: pd.DataFrame,
     engine: EngineType = EngineType.PLOTLY,
@@ -34,11 +36,6 @@ def create_box_plot(
         The file format is automatically inferred from the file extension
         (e.g., '.html', '.png', '.jpeg', '.svg'). Defaults to None, meaning
         the plot will not be saved.
-    **kwargs
-        Keyword arguments for plot configuration. These arguments are
-        validated against the `BoxConfig` Pydantic model. Refer to
-        `vuecore.schemas.basic.box.BoxConfig` for all available
-        options and their descriptions.
 
     Returns
     -------

src/vuecore/plots/basic/line.py

@@ -5,8 +5,10 @@
 from vuecore import EngineType
 from vuecore.engines import get_builder, get_saver
 from vuecore.schemas.basic.line import LineConfig
+from vuecore.utils.docs_utils import document_pydant_params
 
 
+@document_pydant_params(LineConfig)
 def create_line_plot(
     data: pd.DataFrame,
     engine: EngineType = EngineType.PLOTLY,
@@ -34,10 +36,6 @@ def create_line_plot(
         The file format is automatically inferred from the file extension
         (e.g., '.html', '.png', '.jpeg', '.svg'). Defaults to None, meaning
         the plot will not be saved.
-    **kwargs
-        Keyword arguments for plot configuration. These arguments are validated
-        against the `LineConfig` Pydantic model. See
-        `vuecore.schemas.basic.line.LineConfig` for all available options.
 
     Returns
     -------

src/vuecore/plots/basic/scatter.py

@@ -5,8 +5,10 @@
 from vuecore import EngineType
 from vuecore.engines import get_builder, get_saver
 from vuecore.schemas.basic.scatter import ScatterConfig
+from vuecore.utils.docs_utils import document_pydant_params
 
 
+@document_pydant_params(ScatterConfig)
 def create_scatter_plot(
     data: pd.DataFrame,
     engine: EngineType = EngineType.PLOTLY,
@@ -34,10 +36,6 @@ def create_scatter_plot(
         The file format is automatically inferred from the file extension
         (e.g., '.html', '.png', '.jpeg', '.svg'). Defaults to None, meaning
         the plot will not be saved.
-    **kwargs
-        Keyword arguments for plot configuration. These arguments are validated
-        against the `ScatterConfig` Pydantic model. See
-        `schemas.basic.scatter.ScatterConfig` for all available options.
 
     Returns
     -------

src/vuecore/schemas/basic/bar.py

@@ -1,10 +1,12 @@
-from typing import Dict, List, Optional
-from pydantic import BaseModel, Field, ConfigDict
+from typing import Dict, Optional
+from pydantic import Field, ConfigDict
+from vuecore.schemas.plotly_base import PlotlyBaseConfig
 
 
-class BarConfig(BaseModel):
+class BarConfig(PlotlyBaseConfig):
     """
-    Pydantic model for validating and managing bar plot configurations.
+    Pydantic model for validating and managing bar plot configurations,
+    which extends PlotlyBaseConfig.
 
     This model serves as a curated API for the most relevant parameters
     for bar plots, closely aligned with the `plotly.express.bar` API
@@ -16,101 +18,19 @@ class BarConfig(BaseModel):
     defined here, and also accepts additional Plotly keyword arguments,
     forwarding them to the appropriate `plotly.express.bar` or
     `plotly.graph_objects.Figure` call.
-
-    Attributes
-    ----------
-    -----Data Mapping-----
-    x : str
-        Column for the x-axis values.
-    y : str
-        Column for the y-axis values.
-    color : Optional[str]
-        Column to assign color to bars.
-    pattern_shape : Optional[str]
-        Column to assign pattern shapes to bars.
-    hover_name : Optional[str]
-        Column to appear in bold in the hover tooltip.
-    hover_data : Optional[List[str]]
-        Additional columns to display in the hover tooltip.
-    text : Optional[str]
-        Column for adding text labels to bars.
-    facet_row : Optional[str]
-        Column to create vertical subplots (facets).
-    facet_col : Optional[str]
-        Column to create horizontal subplots (facets).
-    error_x : Optional[str]
-        Column for sizing x-axis error bars.
-    error_y : Optional[str]
-        Column for sizing y-axis error bars.
-    labels : Optional[Dict[str, str]]
-        Dictionary to override column names for titles, legends, etc.
-    color_discrete_map : Optional[Dict[str, str]]
-        Specific color mappings for values in the `color` column.
-    pattern_shape_map : Optional[Dict[str, str]]
-        Specific pattern shape mappings for values in the `pattern_shape` column.
-    -----Styling and Layout-----
-    opacity : float
-        Marker opacity (0-1).
-    orientation: str
-        Orientation of the bars ('v' for vertical, 'h' for horizontal).
-    barmode : str
-        Mode for grouping bars ('group', 'overlay', 'relative').
-    log_x : bool
-        If True, the x-axis is log-scaled.
-    log_y : bool
-        If True, the y-axis is log-scaled.
-    range_x : Optional[List[float]]
-        Range for the x-axis, e.g., [0, 100].
-    range_y : Optional[List[float]]
-        Range for the y-axis, e.g., [0, 100].
-    title : str
-        The main title of the plot.
-    x_title : Optional[str]
-        Custom title for the x-axis.
-    y_title : Optional[str]
-        Custom title for the y-axis.
-    subtitle : str
-        The subtitle of the plot.
-    template : str
-        Plotly template for styling (e.g., 'plotly_white').
-    width : int
-        Width of the plot in pixels.
-    height : int
-        Height of the plot in pixels.
     """
 
     # General Configuration
     # Allow extra parameters to pass through to Plotly
     model_config = ConfigDict(extra="allow")
 
     # Data Mapping
-    x: str = Field(..., description="Column for x-axis values.")
-    y: str = Field(..., description="Column for y-axis values.")
-    color: Optional[str] = Field(None, description="Column to assign color to bars.")
     pattern_shape: Optional[str] = Field(
         None, description="Column to assign pattern shapes to bars."
     )
-    hover_name: Optional[str] = Field(
-        None, description="Column for bold text in hover tooltip."
-    )
-    hover_data: List[str] = Field(
-        [], description="Additional columns for the hover tooltip."
-    )
     text: Optional[str] = Field(None, description="Column for text labels on bars.")
-    facet_row: Optional[str] = Field(
-        None, description="Column to create vertical subplots."
-    )
-    facet_col: Optional[str] = Field(
-        None, description="Column to create horizontal subplots."
-    )
     error_x: Optional[str] = Field(None, description="Column for x-axis error bars.")
     error_y: Optional[str] = Field(None, description="Column for y-axis error bars.")
-    labels: Optional[Dict[str, str]] = Field(
-        None, description="Override column names in the plot."
-    )
-    color_discrete_map: Optional[Dict[str, str]] = Field(
-        None, description="Map values to specific colors."
-    )
     pattern_shape_map: Optional[Dict[str, str]] = Field(
         None, description="Map values to specific pattern shapes."
     )
@@ -122,18 +42,3 @@ class BarConfig(BaseModel):
         description="Orientation of the bars ('v' for vertical, 'h' for horizontal).",
     )
     barmode: str = Field("relative", description="Mode for grouping bars.")
-    log_x: bool = Field(False, description="If True, use a logarithmic x-axis.")
-    log_y: bool = Field(False, description="If True, use a logarithmic y-axis.")
-    range_x: Optional[List[float]] = Field(
-        None, description="Range for the x-axis, e.g., [0, 100]."
-    )
-    range_y: Optional[List[float]] = Field(
-        None, description="Range for the y-axis, e.g., [0, 100]."
-    )
-    title: str = Field("Bar Plot", description="The main title of the plot.")
-    x_title: Optional[str] = Field(None, description="Custom title for the x-axis.")
-    y_title: Optional[str] = Field(None, description="Custom title for the y-axis.")
-    subtitle: Optional[str] = Field(None, description="The subtitle for the plot.")
-    template: str = Field("plotly_white", description="Plotly template for styling.")
-    width: int = Field(800, description="Width of the plot in pixels.")
-    height: int = Field(600, description="Height of the plot in pixels.")