Skip to content

Commit 4bcfe15

Browse files
committed
DOC: Improve Axes rcParams descriptions
1 parent e3fc0da commit 4bcfe15

1 file changed

Lines changed: 46 additions & 42 deletions

File tree

‎lib/matplotlib/rcsetup.py‎

Lines changed: 46 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1749,21 +1749,21 @@ class _Subsection:
17491749
default="white",
17501750
type=":mpltype:`color`",
17511751
validator=validate_color,
1752-
description="The axes background color."
1752+
description="Axes background color."
17531753
),
17541754
_Param(
17551755
"axes.edgecolor",
17561756
default="black",
17571757
type=":mpltype:`color`",
17581758
validator=validate_color,
1759-
description="The axes edge color."
1759+
description="Axes edge color."
17601760
),
17611761
_Param(
17621762
"axes.linewidth",
17631763
default=0.8,
17641764
type=float,
17651765
validator=validate_float,
1766-
description="The axes edge line width."
1766+
description="Axes edge line width in points."
17671767
),
17681768
_Param(
17691769
"axes.grid",
@@ -1777,7 +1777,7 @@ class _Subsection:
17771777
default="both",
17781778
type=Literal["x", "y", "both"],
17791779
validator=["x", "y", "both"],
1780-
description="Which axis the grid should apply to."
1780+
description="On which axis the grid is displayed."
17811781
),
17821782
_Param(
17831783
"axes.grid.which",
@@ -1791,82 +1791,86 @@ class _Subsection:
17911791
default="center",
17921792
type=Literal["left", "center", "right"],
17931793
validator=["left", "center", "right"],
1794-
description="The alignment of the axes title."
1794+
description="Horizontal location of the axes title."
17951795
),
17961796
_Param(
17971797
"axes.titlesize",
17981798
default="large",
17991799
type=_FontSizeType,
18001800
validator=validate_fontsize,
1801-
description="The font size of the axes title."
1801+
description="Font size of the axes title."
18021802
),
18031803
_Param(
18041804
"axes.titleweight",
18051805
default="normal",
18061806
type=_FontWeightType,
18071807
validator=validate_fontweight,
1808-
description="The font weight of the axes title."
1808+
description="Font weight of the axes title."
18091809
),
18101810
_Param(
18111811
"axes.titlecolor",
18121812
default="auto",
18131813
type=':mpltype:`color` or "auto"',
18141814
validator=validate_color_or_auto,
1815-
description="The color of the axes title; auto falls back to 'text.color'."
1815+
description="Color of the axes title; 'auto' falls back to 'text.color'."
18161816
),
18171817
_Param(
18181818
"axes.titley",
18191819
default=None,
18201820
type=float | None,
18211821
validator=validate_float_or_None,
1822-
description="The vertical title position in "
1823-
":ref:`axes coordinates <coordinate-systems>`; "
1824-
"None enables automatic placement."
1822+
description="Vertical axes title position.\n\n"
1823+
"A number specifies the text baseline in "
1824+
":ref:`axes coordinates <coordinate-systems>`. "
1825+
"None enables automatic placement so that the title bottom aligns "
1826+
"with the top of the Axes and potentially any top tick "
1827+
"labels.\n\n"
1828+
"The position will additionally be shifted by 'axes.titlepad'."
18251829
),
18261830
_Param(
18271831
"axes.titlepad",
18281832
default=6.0,
18291833
type=float,
18301834
validator=validate_float,
1831-
description="The padding between the axes and title, in points."
1835+
description="Additional space between the Axes and title in points. This "
1836+
"shifts the title position determined by 'axes.titley'. "
18321837
),
18331838
_Param(
18341839
"axes.labelsize",
18351840
default="medium",
18361841
type=_FontSizeType,
18371842
validator=validate_fontsize,
1838-
description="The font size of the x and y labels."
1843+
description="Font size of the x and y labels."
18391844
),
18401845
_Param(
18411846
"axes.labelpad",
18421847
default=4.0,
18431848
type=float,
18441849
validator=validate_float,
1845-
description="The space between the axis label and the axis, in points."
1850+
description="The space between the axis label and the axis / tick labels, "
1851+
"in points."
18461852
),
18471853
_Param(
18481854
"axes.labelweight",
18491855
default="normal",
18501856
type=_FontWeightType,
18511857
validator=validate_fontweight,
1852-
description="The font weight of the x and y labels."
1858+
description="Font weight of the x and y labels."
18531859
),
18541860
_Param(
18551861
"axes.labelcolor",
18561862
default="black",
18571863
type=":mpltype:`color`",
18581864
validator=validate_color,
1859-
description="The color of the axis labels."
1865+
description="Color of the axis labels."
18601866
),
18611867
_Param(
18621868
"axes.axisbelow",
18631869
default="line",
18641870
type=bool | Literal["line"],
18651871
validator=validate_axisbelow,
1866-
description="draw axis gridlines and ticks: "
1867-
"- below patches (True) "
1868-
"- above patches but below lines ('line') "
1869-
"- above all (False)"
1872+
description="Whether axis ticks and gridlines are above or below most artists. "
1873+
"See `~.Axes.set_axisbelow` for details."
18701874
),
18711875
_Param(
18721876
"axes.formatter.limits",
@@ -1881,22 +1885,26 @@ class _Subsection:
18811885
default=False,
18821886
type=bool,
18831887
validator=validate_bool,
1884-
description="When True, format tick labels according to the user's locale. "
1888+
description="Whether to format tick labels according to the user's locale. "
18851889
"For example, use ',' as a decimal separator in the fr_FR locale."
18861890
),
18871891
_Param(
18881892
"axes.formatter.use_mathtext",
18891893
default=False,
18901894
type=bool,
18911895
validator=validate_bool,
1892-
description="When True, use mathtext for scientific notation."
1896+
description="Whether `.ScalarFormatter` and `.EngFormatter` use fancy "
1897+
r"formatting for scientific notation; i.e. :math:`1.2 \times 10^3` "
1898+
"instead of 1.2e3."
18931899
),
18941900
_Param(
18951901
"axes.formatter.min_exponent",
18961902
default=0,
18971903
type=int,
18981904
validator=validate_int,
1899-
description="minimum exponent to format in scientific notation"
1905+
description="The smallest absolute exponent value that log formatters will "
1906+
"format as scientific notation; e.g. if set to 3, formatting will "
1907+
"1e-3, 0.01, 0.1, 0, 10, 100, 1e3."
19001908
),
19011909
_Param(
19021910
"axes.formatter.useoffset",
@@ -1916,27 +1924,23 @@ class _Subsection:
19161924
"remove at least this number of significant digits from tick "
19171925
"labels."
19181926
),
1919-
_Param(
1920-
"axes.spines.left",
1921-
default=True,
1922-
type=bool,
1923-
validator=validate_bool,
1924-
description="display axis spines"
1925-
),
1926-
_Param("axes.spines.bottom", True, bool, validate_bool,
1927+
_Param("axes.spines.left", default=True, type=bool, validator=validate_bool,
1928+
description="Whether to draw the left axis spine."),
1929+
_Param("axes.spines.bottom", default=True, type=bool, validator=validate_bool,
19271930
description="Whether to draw the bottom axis spine."),
1928-
_Param("axes.spines.top", True, bool, validate_bool,
1931+
_Param("axes.spines.top", default=True, type=bool, validator=validate_bool,
19291932
description="Whether to draw the top axis spine."),
1930-
_Param("axes.spines.right", True, bool, validate_bool,
1933+
_Param("axes.spines.right", default=True, type=bool, validator=validate_bool,
19311934
description="Whether to draw the right axis spine."),
19321935
_Param(
19331936
"axes.unicode_minus",
19341937
default=True,
19351938
type=bool,
19361939
validator=validate_bool,
1937-
description="use Unicode for the minus symbol rather than hyphen. See "
1938-
"https://en.wikipedia.org/wiki/Plus_and_minus_signs#Character_codes"
1939-
1940+
description="Whether formatters will use the Unicode *Minus Sign* symbol "
1941+
"U+2212 (\N{MINUS SIGN}) rather than the ASCII hyphen U+002D (-) "
1942+
"for negative numbers. See also "
1943+
":doc:`/gallery/text_labels_and_annotations/unicode_minus`."
19401944
),
19411945
_Param(
19421946
"axes.prop_cycle",
@@ -1963,30 +1967,30 @@ class _Subsection:
19631967
default=0.05,
19641968
type=float,
19651969
validator=_validate_greaterthan_minushalf,
1966-
description="x margin. See `~.axes.Axes.margins`"
1970+
description="x margin. See `~.axes.Axes.margins`."
19671971
),
19681972
_Param(
19691973
"axes.ymargin",
19701974
default=0.05,
19711975
type=float,
19721976
validator=_validate_greaterthan_minushalf,
1973-
description="y margin. See `~.axes.Axes.margins`"
1977+
description="y margin. See `~.axes.Axes.margins`."
19741978
),
19751979
_Param(
19761980
"axes.zmargin",
19771981
default=0.05,
19781982
type=float,
19791983
validator=_validate_greaterthan_minushalf,
1980-
description="z margin. See `~.axes.Axes.margins`"
1984+
description="z margin. See `~.axes.Axes.margins`."
19811985
),
19821986
_Param(
19831987
"axes.autolimit_mode",
19841988
default="data",
19851989
type=Literal["data", "round_numbers"],
19861990
validator=["data", "round_numbers"],
1987-
description='If "data", use axes.xmargin and axes.ymargin as is. If '
1988-
'"round_numbers", after application of margins, axis limits are '
1989-
'further expanded to the nearest "round" number.',
1991+
description='Whether autoscaling should try to adjust the view limits so that '
1992+
'there are ticks at the the axis edges. See '
1993+
':ref:`autoscaling-limit-rounding`.'
19901994
),
19911995
_Subsection("Polar Axes"),
19921996
_Param(

0 commit comments

Comments
 (0)