Skip to content

Clarify/Improve docs on family-names vs generic-families #20346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jklymak merged 2 commits into from
Jun 11, 2021
Merged

Clarify/Improve docs on family-names vs generic-families #20346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
84046cb
Clarify family-names vs generic-families
aitikgupta Jun 11, 2021
61abd44
Clarify doc and best practice
aitikgupta Jun 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions examples/text_labels_and_annotations/font_family_rc_sgskip.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,17 @@
Configuring the font family
===========================

You can explicitly set which font family is picked up for a given font
style (e.g., 'serif', 'sans-serif', or 'monospace').
You can explicitly set which font family is picked up, either by specifying
family names of fonts installed on user's system, or generic-families
(e.g., 'serif', 'sans-serif', 'monospace', 'fantasy' or 'cursive'),
or a combination of both.
(see :doc:`font tutorial </tutorials/text/text_props>`)

In the example below, we only allow one font family (Tahoma) for the
sans-serif font style. The default family is set with the font.family rcparam,
In the example below, we are overriding the default sans-serif generic family
to include a specific (Tahoma) font. (Note that the best way to achieve this
would simply be to prepend 'Tahoma' in 'font.family')

The default family is set with the font.family rcparam,
e.g. ::

rcParams['font.family'] = 'sans-serif'
Expand Down
49 changes: 37 additions & 12 deletions tutorials/text/text_props.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,9 +149,9 @@
# +---------------------+----------------------------------------------------+
# | rcParam | usage |
# +=====================+====================================================+
# | ``'font.family'`` | List of either names of font or ``{'cursive', |
# | | 'fantasy', 'monospace', 'sans', 'sans serif', |
# | | 'sans-serif', 'serif'}``. |
# | ``'font.family'`` | List of font families (installed on user's machine)|
# | | and/or ``{'cursive', 'fantasy', 'monospace', |
# | | 'sans', 'sans serif', 'sans-serif', 'serif'}``. |
# | | |
# +---------------------+----------------------------------------------------+
# | ``'font.style'`` | The default style, ex ``'normal'``, |
Expand All @@ -174,13 +174,18 @@
# | | this size. |
# +---------------------+----------------------------------------------------+
#
# The mapping between the family aliases (``{'cursive', 'fantasy',
# 'monospace', 'sans', 'sans serif', 'sans-serif', 'serif'}``) and actual font names
# Matplotlib can use font families installed on the user's computer, i.e.
# Helvetica, Times, etc. Font families can also be specified with
# generic-family aliases like (``{'cursive', 'fantasy', 'monospace',
# 'sans', 'sans serif', 'sans-serif', 'serif'}``).
#
# The mapping between the generic family aliases and actual font families
# (mentioned at :doc:`default rcParams </tutorials/introductory/customizing>`)
# is controlled by the following rcParams:
#
#
# +------------------------------------------+--------------------------------+
# | family alias | rcParam with mappings |
# | CSS-based generic-family alias | rcParam with mappings |
# +==========================================+================================+
# | ``'serif'`` | ``'font.serif'`` |
# +------------------------------------------+--------------------------------+
Expand All @@ -194,7 +199,15 @@
# +------------------------------------------+--------------------------------+
#
#
# which are lists of font names.
# If any of generic family names appear in ``'font.family'``, we replace that entry
# by all the entries in the corresponding rcParam mapping.
# For example: ::
#
# matplotlib.rcParams['font.family'] = ['Family1', 'serif', 'Family2']
# matplotlib.rcParams['font.serif'] = ['SerifFamily1', 'SerifFamily2']
#
# # This is effectively translated to:
# matplotlib.rcParams['font.family'] = ['Family1', 'SerifFamily1', 'SerifFamily2', 'Family2']
#
# Text with non-latin glyphs
# ==========================
Expand All @@ -204,14 +217,26 @@
# Korean, or Japanese.
#
# To set the default font to be one that supports the code points you
# need, prepend the font name to ``'font.family'`` or the desired alias
# lists ::
# need, prepend the font name to ``'font.family'`` (recommended), or to the
# desired alias lists. ::
#
# # first method
# matplotlib.rcParams['font.family'] = ['Source Han Sans TW', 'sans-serif']
#
# # second method
# matplotlib.rcParams['font.family'] = ['sans-serif']
# matplotlib.rcParams['sans-serif'] = ['Source Han Sans TW', ...]
#
# The generic family alias lists contain fonts that are either shipped
# alongside Matplotlib (so they have 100% chance of being found), or fonts
# which have a very high probability of being present in most systems.
#
# matplotlib.rcParams['font.sans-serif'] = ['Source Han Sans TW', 'sans-serif']
# A good practice when setting custom font families is to append
# a generic-family to the font-family list as a last resort.
#
# or set it in your :file:`.matplotlibrc` file::
# You can also set it in your :file:`.matplotlibrc` file::
#
# font.sans-serif: Source Han Sans TW, Arial, sans-serif
# font.family: Source Han Sans TW, Arial, sans-serif
#
# To control the font used on per-artist basis use the *name*, *fontname* or
# *fontproperties* keyword arguments documented :doc:`above
Expand Down