DOC: Fix markup in docstrings

plotnine/animation.py

@@ -28,17 +28,17 @@ class PlotnineAnimation(ArtistAnimation):
 
     Parameters
     ----------
-    plots : iterable
+    plots :
         ggplot objects that make up the the frames of the animation
-    interval : number, optional
+    interval : int
         Delay between frames in milliseconds. Defaults to 200.
-    repeat_delay : number, optional
+    repeat_delay : int
         If the animation in repeated, adds a delay in milliseconds
         before repeating the animation. Defaults to `None`.
-    repeat : bool, optional
+    repeat : bool
         Controls whether the animation should repeat when the sequence
         of frames is completed. Defaults to `True`.
-    blit : bool, optional
+    blit : bool
         Controls whether blitting is used to optimize drawing. Defaults
         to `False`.
 

plotnine/coords/coord_fixed.py

@@ -19,11 +19,11 @@ class coord_fixed(coord_cartesian):
     ----------
     ratio : float
         Desired aspect_ratio (:math:`y/x`) of the panel(s).
-    xlim : tuple[float, float], default=None
+    xlim : tuple[float, float]
         Limits for x axis. If None, then they are automatically computed.
-    ylim : tuple[float, float], default=None
+    ylim : tuple[float, float]
         Limits for y axis. If None, then they are automatically computed.
-    expand : bool, default=True
+    expand : bool
         If `True`, expand the coordinate axes by some factor. If `False`,
         use the limits from the data.
 

plotnine/coords/coord_trans.py

@@ -35,11 +35,11 @@ class coord_trans(coord):
         Name of transform or `trans` class to transform the x axis
     y : str | trans
         Name of transform or `trans` class to transform the y axis
-    xlim : tuple[float, float], default=None
+    xlim : tuple[float, float]
         Limits for x axis. If None, then they are automatically computed.
-    ylim : tuple[float, float], default=None
+    ylim : tuple[float, float]
         Limits for y axis. If None, then they are automatically computed.
-    expand : bool, default=True
+    expand : bool
         If `True`, expand the coordinate axes by some factor. If `False`,
         use the limits from the data.
     """

plotnine/doctools.py

@@ -54,7 +54,7 @@
 AESTHETICS_TABLE_TPL = """
 {table}
 
-The **bold** aesthetics are required."""
+The _emphasized_ aesthetics are required."""
 
 STAT_SIGNATURE_TPL = """
 **Usage**
@@ -106,15 +106,15 @@
     {_aesthetics_doc}
 data : dataframe, default=None
     {data}
-stat : str or stat, default={default_stat}
+stat : str | stat, default="{default_stat}"
     {stat}
-position : str or position, default={default_position}
+position : str | position, default="{default_position}"
     {position}
 na_rm : bool, default={default_na_rm}
     {na_rm}
 inherit_aes : bool, default={default_inherit_aes}
     {inherit_aes}
-show_legend : bool or dict, default=None
+show_legend : bool | dict, default=None
     {show_legend}
 raster : bool, default={default_raster}
     {raster}
@@ -126,9 +126,9 @@
     {_aesthetics_doc}
 data : dataframe, default=None
     {data}
-geom : str or geom, default={default_geom}
+geom : str | geom, default="{default_geom}"
     {stat}
-position : str or position, default={default_position}
+position : str | position, default="{default_position}"
     {position}
 na_rm : bool, default={default_na_rm}
     {na_rm}
@@ -291,7 +291,7 @@ def param_spec(line: str) -> str | None:
 
     Returns
     -------
-    name : str or None
+    name : str | None
         Name of the parameter if the line for the parameter
         type specification and None otherwise.
 
@@ -412,7 +412,7 @@ def document_geom(geom: type[Geom]) -> type[Geom]:
     usage = GEOM_SIGNATURE_TPL.format(signature=signature)
 
     # aesthetics
-    contents = {f"**{ae}**": "" for ae in sorted(geom.REQUIRED_AES)}
+    contents = {f"_{ae}_": "" for ae in sorted(geom.REQUIRED_AES)}
     if geom.DEFAULT_AES:
         d = geom.DEFAULT_AES.copy()
         d["group"] = ""  # All geoms understand the group aesthetic

plotnine/facets/facet.py

@@ -40,7 +40,7 @@ class facet:
 
     Parameters
     ----------
-    scales : "fixed", "free", "free_x", "free_y", default="fixed"
+    scales : "fixed" | "free" | "free_x" | "free_y", default="fixed"
         Whether `x` or `y` scales should be allowed (free)
         to vary according to the data on each of the panel.
     shrink : bool
@@ -49,7 +49,7 @@ class facet:
     shrink : bool, default=True
         Whether to shrink the scales to the output of the
         statistics instead of the raw data.
-    labeller : str, callable, default="label_value"
+    labeller : str | callable, default="label_value"
         How to label the facets. A string value if it should be
         one of `["label_value", "label_both", "label_context"]`{.py}.
     as_table : bool, default=True
@@ -62,12 +62,12 @@ class facet:
         will automatically be dropped. If `False`, all
         factor levels will be shown, regardless of whether
         or not they appear in the data.
-    dir : "h", "v", default="h"
+    dir : "h" | "v", default="h"
         Direction in which to layout the panels. `h` for
         horizontal and `v` for vertical.
     """
 
-    #: number of columns
+    # , number of columns
     ncol: int
     #: number of rows
     nrow: int

plotnine/facets/facet_grid.py

@@ -59,13 +59,15 @@ class facet_grid(facet):
         The size also depends to the `scales` parameter.
 
         If a string, it should be one of
-        ``['fixed', 'free', 'free_x', 'free_y']``. Currently, only the
-        ``'fixed'`` option is supported.
+        `['fixed', 'free', 'free_x', 'free_y']`{.py}.
+        Currently, only the `'fixed'` option is supported.
 
         Alternatively if a `dict`, it indicates the relative facet
-        size ratios such as::
+        size ratios such as:
 
-            {'x': [1, 2], 'y': [3, 1, 1]}
+        ```python
+        {"x": [1, 2], "y": [3, 1, 1]}
+        ```
 
         This means that in the horizontal direction, the second panel
         will be twice the length of the first. In the vertical direction
@@ -74,11 +76,10 @@ class facet_grid(facet):
 
         Note that the number of dimensions in the list must equal the
         number of facets that will be produced.
-
     shrink : bool, default=True
         Whether to shrink the scales to the output of the
         statistics instead of the raw data.
-    labeller : str, callable, default="label_value"
+    labeller : str | callable, default="label_value"
         How to label the facets. A string value if it should be
         one of `["label_value", "label_both", "label_context"]`{.py}.
     as_table : bool, default=True

plotnine/facets/facet_wrap.py

@@ -31,21 +31,21 @@ class facet_wrap(facet):
 
     Parameters
     ----------
-    facets : str| tuple
+    facets : str | tuple
         Variables to groupby and plot on different panels.
         If a string formula is used it should be right sided,
         e.g `"~ a + b"`, `("a", "b")`
     nrow : int, default=None
         Number of rows
     ncol : int, default=None
         Number of columns
-    scales : "fixed", "free", "free_x", "free_y", default="fixed"
+    scales : "fixed" | "free" | "free_x" | "free_y", default="fixed"
         Whether `x` or `y` scales should be allowed (free)
         to vary according to the data on each of the panel.
     shrink : bool, default=True
         Whether to shrink the scales to the output of the
         statistics instead of the raw data.
-    labeller : str, callable, default="label_value"
+    labeller : str | callable, default="label_value"
         How to label the facets. A string value if it should be
         one of `["label_value", "label_both", "label_context"]`{.py}.
     as_table : bool, default=True
@@ -58,7 +58,7 @@ class facet_wrap(facet):
         will automatically be dropped. If `False`, all
         factor levels will be shown, regardless of whether
         or not they appear in the data.
-    dir : "h", "v", default="h"
+    dir : "h" | "v", default="h"
         Direction in which to layout the panels. `h` for
         horizontal and `v` for vertical.
     """

plotnine/facets/labelling.py

@@ -54,7 +54,7 @@ def label_both(
         Label information to be modified.
     multi_line : bool
         Whether to place each variable on a separate line
-    sep :  str
+    sep : str
         Separation between variable name and value
 
     Returns
@@ -88,7 +88,7 @@ def label_context(
         Label information
     multi_line : bool
         Whether to place each variable on a separate line
-    sep :  str
+    sep : str
         Separation between variable name and value
 
     Returns
@@ -120,9 +120,9 @@ def as_labeller(
 
     Parameters
     ----------
-    x : function | dict
+    x : callable | dict
         Object to coerce
-    default : str | function
+    default : str | callable
         Default labeller. If it is a string,
         it should be the name of one the labelling
         functions provided by plotnine.
@@ -153,13 +153,13 @@ class labeller:
 
     Parameters
     ----------
-    rows : str, callable
+    rows : str | callable
         How to label the rows
-    cols : str, callable
+    cols : str | callable
         How to label the columns
     multi_line : bool
         Whether to place each variable on a separate line
-    default : str, callable
+    default : str | callable
         Fallback labelling function. If it is a string, it should be
         one of `["label_value", "label_both", "label_context"]`{.py}.
     kwargs : dict

plotnine/geoms/annotate.py

@@ -22,7 +22,7 @@ class annotate:
 
     Parameters
     ----------
-    geom : geom or str
+    geom : geom | str
         geom to use for annotation, or name of geom (e.g. 'point').
     x : float
         Position

plotnine/geoms/annotation_logticks.py

@@ -77,11 +77,11 @@ def _check_log_scale(
 
         Parameters
         ----------
-        base : float or None
+        base : float | None
             Base of the logarithm in which the ticks will be
             calculated. If `None`, the base of the log transform
             the scale will be used.
-        sides : str (default: bl)
+        sides : str, default="bl"
             Sides onto which to draw the marks. Any combination
             chosen from the characters `btlr`, for *bottom*, *top*,
             *left* or *right* side marks. If `coord_flip()` is used,
@@ -251,23 +251,23 @@ class annotation_logticks(annotate):
 
     Parameters
     ----------
-    sides : str (default: bl)
+    sides : str, default="bl"
         Sides onto which to draw the marks. Any combination
         chosen from the characters `btlr`, for *bottom*, *top*,
         *left* or *right* side marks. If `coord_flip()` is used,
         these are the sides *after* the flip.
-    alpha : float (default: 1)
+    alpha : float, default=1)
         Transparency of the ticks
-    color : str | tuple (default: 'black')
+    color : str | tuple, default="black"
         Colour of the ticks
     size : float
         Thickness of the ticks
-    linetype : 'solid' | 'dashed' | 'dashdot' | 'dotted' | tuple
-        Type of line. Default is *solid*.
-    lengths: tuple (default (0.036, 0.0225, 0.012))
+    linetype : "solid" | "dashed" | "dashdot" | "dotted" | tuple[float]
+        Type of line
+    lengths: tuple[float], default=(0.036, 0.0225, 0.012)
         length of the ticks drawn for full / half / tenth
         ticks relative to panel size
-    base : float (default: None)
+    base : float, default=None
         Base of the logarithm in which the ticks will be
         calculated. If `None`, the base used to log transform
         the scale will be used.

plotnine/geoms/annotation_stripes.py

@@ -29,29 +29,28 @@ class annotation_stripes(annotate):
     Parameters
     ----------
     fill : list-like
-        List of colors for the strips. The default  is
-        `("#AAAAAA", "#CCCCCC")`
-    fill_range: 'cycle' | 'nocycle' | 'auto' | 'no'
-        How to fill stripes beyond the range of scale::
-
-            'cycle'      # keep cycling the colors of the
-                         # stripes after the range ends
-            'nocycle'    # stop cycling the colors of the
-                         # stripes after the range ends
-            'auto'       # 'cycle' for continuous scales and
-                         # 'nocycle' for discrete scales.
-            'no'         # Do not add stripes passed the range
-                         # passed the range of the scales
-
-        Default is 'auto'.
-    direction : 'vertical' or 'horizontal'
+        List of colors for the strips.
+    fill_range: "cycle" | "nocycle" | "auto" | "no"
+        How to fill stripes beyond the range of scale:
+
+        ```python
+        "cycle"      # keep cycling the colors of the
+                     # stripes after the range ends
+        "nocycle"    # stop cycling the colors of the
+                     # stripes after the range ends
+        "auto"       # "cycle" for continuous scales and
+                     # "nocycle" for discrete scales.
+        "no"         # Do not add stripes passed the range
+                     # passed the range of the scales
+        ```
+    direction : "vertical" | "horizontal"
         Orientation of the stripes
     extend : tuple
         Range of the stripes. The default is (0, 1), top to bottom.
         The values should be in the range [0, 1].
     **kwargs : dict
         Other aesthetic parameters for the rectangular stripes.
-        They include; *alpha*, *color*, *linetype*, and *size*.
+        They include; `alpha`, `color`, `linetype`, and `size`.
     """
 
     def __init__(