Write docstrings

mckinsey · Nov 28, 2023 · 8d9988a · 8d9988a
1 parent 5f5ceba
commit 8d9988a
Show file tree

Hide file tree

Showing 5 changed files with 20 additions and 32 deletions.
diff --git a/vizro-core/src/vizro/models/_navigation/accordion.py b/vizro-core/src/vizro/models/_navigation/accordion.py
@@ -20,14 +20,11 @@ class Accordion(VizroBaseModel):
 
     Args:
         type (Literal["accordion"]): Defaults to `"accordion"`.
-        pages (Optional[Dict[str, List[str]])]: A dictionary with a page group title as key and a list of page IDs as
-            values.
+        pages (Dict[str, List[str]]): Mapping from name of a pages group to a list of page IDs. Defaults to `{}`.
     """
 
     type: Literal["accordion"] = "accordion"
-    pages: Dict[str, List[str]] = Field(
-        {}, description="A dictionary with a page group title as key and a list of page IDs as values."
-    )
+    pages: Dict[str, List[str]] = Field({}, description="Mapping from name of a pages group to a list of page IDs.")
 
     _validate_pages = validator("pages", allow_reuse=True)(_validate_pages)
 

diff --git a/vizro-core/src/vizro/models/_navigation/nav_bar.py b/vizro-core/src/vizro/models/_navigation/nav_bar.py
@@ -17,15 +17,12 @@ class NavBar(VizroBaseModel):
 
     Args:
         type (Literal["nav_bar"]): Defaults to `"nav_bar"`.
-        pages (Optional[Dict[str, List[str]]]): A dictionary with a page group title as key and a list of page IDs as
-            values.
-        items (Optional[List[NavLink]]): See [`NavLink`][vizro.models.NavLink]. Defaults to `[]`.
+        pages (Dict[str, List[str]]): Mapping from name of a pages group to a list of page IDs. Defaults to `{}`.
+        items (List[NavLink]): See [`NavLink`][vizro.models.NavLink]. Defaults to `[]`.
     """
 
     type: Literal["nav_bar"] = "nav_bar"
-    pages: Dict[str, List[str]] = Field(
-        {}, description="A dictionary with a page group title as key and a list of page IDs as values."
-    )
+    pages: Dict[str, List[str]] = Field({}, description="Mapping from name of a pages group to a list of page IDs.")
     items: List[NavLink] = []
 
     # validators

diff --git a/vizro-core/src/vizro/models/_navigation/nav_link.py b/vizro-core/src/vizro/models/_navigation/nav_link.py
@@ -19,16 +19,17 @@ class NavLink(VizroBaseModel):
     """Icon to be used in Navigation Panel of Dashboard.
 
     Args:
-        pages (NavPagesType): See [NavPagesType][vizro.models.types.NavPagesType].
-        icon (str): Name of the icon from the Google Material Icon library. For more available
-            icons visit [Google Material Icon library](https://fonts.google.com/icons).
-        label (Optional[str]): Text to be displayed below the icon. It automatically gets truncated to the
-            `max_label_length`. Defaults to `None`.
+        ages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].
+            Defaults to `[]`.
+        label (str): Text description of the icon for use in tooltip.
+        icon (Optional[str]): Icon name from [Google Material icons library](https://fonts.google.com/icons).
+            Defaults to `None`.
+
     """
 
     pages: NavPagesType = []
-    label: str = Field(..., description="Text to be displayed below the icon.")
-    icon: Optional[str] = Field(None, description="Icon name from Google Material Icon library.")
+    label: str = Field(..., description="Text description of the icon for use in tooltip.")
+    icon: Optional[str] = Field(None, description="Icon name from Google Material icons library.")
 
     _nav_selector: Accordion = PrivateAttr()
 

diff --git a/vizro-core/src/vizro/models/_navigation/navigation.py b/vizro-core/src/vizro/models/_navigation/navigation.py
@@ -15,7 +15,7 @@ class Navigation(VizroBaseModel):
 
     Args:
         pages (Optional[NavPagesType]): See [`NavPagesType`][vizro.models.types.NavPagesType].
-            Defaults to `None`.
+            Defaults to [].
         nav_selector (Optional[NavSelectorType]): See [`NavSelectorType`][vizro.models.types.NavSelectorType].
             Defaults to `None`.
     """

diff --git a/vizro-core/src/vizro/models/types.py b/vizro-core/src/vizro/models/types.py
@@ -308,7 +308,7 @@ class OptionsDictType(TypedDict):
     Union[SelectorType, "Button", "UserInput"],
     Field(
         discriminator="type",
-        description="Components that can be used to receive user input within a form'.",
+        description="Components that can be used to receive user input within a form.",
     ),
 ]
 
@@ -333,19 +333,12 @@ class OptionsDictType(TypedDict):
 [`Button`][vizro.models.Button], [`Card`][vizro.models.Card], [`Table`][vizro.models.Table] or
 [`Graph`][vizro.models.Graph]."""
 
-NavPagesType = Annotated[
-    Union[List[str], Dict[str, List[str]]],
-    Field(
-        ...,
-        description="List of Page IDs or dict mapping of Page IDs and titles (for hierarchical sub-navigation)",
-    ),
-]
-"""Permissible value types for page attribute. Values are displayed as default."""
+NavPagesType = Union[List[str], Dict[str, List[str]]]
+"List of page IDs or a mapping from name of a group to a list of page IDs (for hierarchical sub-navigation)."
 
 NavSelectorType = Annotated[
     Union["Accordion", "NavBar"],
-    Field(discriminator="type", description="Component that makes up part of the navigation panel"),
+    Field(discriminator="type", description="Component for rendering navigation."),
 ]
-"""Discriminated union. Permissible value types for selector attribute:
-[`Accordion`][vizro.models.Accordion], [`NavBar`][vizro.models.NavBar]."""
-# AM: docstrings
+"""Discriminated union. Type of component for rendering navigation:
+[`Accordion`][vizro.models.Accordion] or [`NavBar`][vizro.models.NavBar]."""