Improve API documentation and complete it (#1554)

bqplot · Jan 31, 2023 · 61ecb83 · 61ecb83
1 parent 48ba3d4
commit 61ecb83
Show file tree

Hide file tree

Showing 15 changed files with 576 additions and 285 deletions.
diff --git a/bqplot/axes.py b/bqplot/axes.py
@@ -63,7 +63,7 @@ class Axis(BaseAxis):
 
     """A line axis.
 
-    A line axis is the visual representation of a numerical or date scale.
+    A line axis is the visual representation of a **numerical** or **date scale**.
 
     Attributes
     ----------
@@ -155,7 +155,7 @@ class ColorAxis(Axis):
 
     """A colorbar axis.
 
-    A color axis is the visual representation of a color scale.
+    A color axis is the visual representation of a **color scale**.
 
     Attributes
     ----------

diff --git a/bqplot/figure.py b/bqplot/figure.py
@@ -51,6 +51,9 @@ class Figure(DOMWidget):
     Besides, the Figure object has two reference scales, for positioning items
     in an absolute fashion in the figure canvas.
 
+    Style Attributes
+    ----------------
+
     Attributes
     ----------
     title: string (default: '')
@@ -84,14 +87,17 @@ class Figure(DOMWidget):
         CSS style to be applied to the title of the figure
     animation_duration: nonnegative int (default: 0)
         Duration of transition on change of data attributes, in milliseconds.
+
+    Layout Attributes
+    -----------------
+
+    Attributes
+    ----------
     pixel_ratio:
         Pixel ratio of the WebGL canvas (2 on retina screens). Set to 1 for better performance,
         but less crisp edges. If set to None it will use the browser's window.devicePixelRatio.
     display_toolbar: boolean (default: True)
         Show or hide the integrated toolbar.
-
-    Layout Attributes
-
     fig_margin: dict (default: {top=60, bottom=60, left=60, right=60})
         Dictionary containing the top, bottom, left and right margins. The user
         is responsible for making sure that the width and height are greater
@@ -101,30 +107,21 @@ class Figure(DOMWidget):
     max_aspect_ratio: float
          maximum width / height ratio of the figure
 
-    Methods
-    -------
+    !!! Note
 
-    save_png:
-       Saves the figure as a PNG file
-    save_svg:
-       Saves the figure as an SVG file
+        The aspect ratios stand for width / height ratios.
 
-    Note
-    ----
+        - If the available space is within bounds in terms of min and max aspect
+        ratio, we use the entire available space.
+        - If the available space is too oblong horizontally, we use the client
+        height and the width that corresponds max_aspect_ratio (maximize width
+        under the constraints).
+        - If the available space is too oblong vertically, we use the client width
+        and the height that corresponds to min_aspect_ratio (maximize height
+        under the constraint).
+        This corresponds to maximizing the area under the constraints.
 
-    The aspect ratios stand for width / height ratios.
-
-     - If the available space is within bounds in terms of min and max aspect
-       ratio, we use the entire available space.
-     - If the available space is too oblong horizontally, we use the client
-       height and the width that corresponds max_aspect_ratio (maximize width
-       under the constraints).
-     - If the available space is too oblong vertically, we use the client width
-       and the height that corresponds to min_aspect_ratio (maximize height
-       under the constraint).
-       This corresponds to maximizing the area under the constraints.
-
-    Default min and max aspect ratio are both equal to 16 / 9.
+        Default min and max aspect ratio are both equal to 16 / 9.
     """
     title = Unicode().tag(sync=True, display_name='Title')
     axes = List(Instance(Axis)).tag(sync=True, **widget_serialization)
@@ -202,7 +199,6 @@ def get_png_data(self, callback, scale=None):
         ----------
         callback: callable
             Called with the PNG data as the only positional argument.
-
         scale: float (default: None)
             Scale up the png resolution when scale > 1, when not given base this on the screen pixel ratio.
         '''

diff --git a/bqplot/market_map.py b/bqplot/market_map.py
@@ -40,7 +40,7 @@
 
 class MarketMap(DOMWidget):
 
-    """Waffle wrapped map.
+    """Waffle wrapped map. A MarketMap is not a Mark, it's a custom Figure!
 
     Attributes
     ----------
@@ -88,6 +88,10 @@ class MarketMap(DOMWidget):
         True, the finer elements are blurred
 
     Map Drawing Attributes
+    ----------------------
+
+    Attributes
+    ----------
     cols: int
         Suggestion for no of columns in the map.If not specified, value is
         inferred from the no of rows and no of cells
@@ -104,7 +108,10 @@ class MarketMap(DOMWidget):
         more square cells for each of the groups
 
     Layout Attributes
+    -----------------
 
+    Attributes
+    ----------
     map_margin: dict (default: {top=50, bottom=50, left=50, right=50})
         Dictionary containing the top, bottom, left and right margins. The user
         is responsible for making sure that the width and height are greater
@@ -116,7 +123,10 @@ class MarketMap(DOMWidget):
 
 
     Display Attributes
+    ------------------
 
+    Attributes
+    ----------
     colors: list of colors
         Colors for each of the groups which are cycled over to cover all the
         groups
@@ -136,30 +146,31 @@ class MarketMap(DOMWidget):
         CSS style for the text of each cell
 
     Other Attributes
+    ----------------
 
+    Attributes
+    ----------
     enable_select: bool
         boolean to control the ability to select the cells of the map by
         clicking
     enable_hover: bool
         boolean to control if the map should be aware of which cell is being
         hovered on. If it is set to False, tooltip will not be displayed
 
-    Note
-    ----
-
-    The aspect ratios stand for width / height ratios.
+    !!! Note
+        The aspect ratios stand for width / height ratios.
 
-     - If the available space is within bounds in terms of min and max aspect
-       ratio, we use the entire available space.
-     - If the available space is too oblong horizontally, we use the client
-       height and the width that corresponds max_aspect_ratio (maximize width
-       under the constraints).
-     - If the available space is too oblong vertically, we use the client width
-       and the height that corresponds to min_aspect_ratio (maximize height
-       under the constraint).
-       This corresponds to maximizing the area under the constraints.
+        - If the available space is within bounds in terms of min and max aspect
+        ratio, we use the entire available space.
+        - If the available space is too oblong horizontally, we use the client
+        height and the width that corresponds max_aspect_ratio (maximize width
+        under the constraints).
+        - If the available space is too oblong vertically, we use the client width
+        and the height that corresponds to min_aspect_ratio (maximize height
+        under the constraint).
+        This corresponds to maximizing the area under the constraints.
 
-    Default min and max aspect ratio are both equal to 16 / 9.
+        Default min and max aspect ratio are both equal to 16 / 9.
     """
     names = Array([]).tag(sync=True, **array_serialization)
     groups = Array([]).tag(sync=True, **array_serialization)