DOC: add ft2font to API docs

tacaswell · tacaswell · commit e836f9ad9de1 · 2022-07-09T19:59:34.000-04:00
diff --git a/doc/api/ft2font.rst b/doc/api/ft2font.rst
@@ -0,0 +1,8 @@
+**********************
+``matplotlib.ft2font``
+**********************
+
+.. automodule:: matplotlib.ft2font
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -120,6 +120,7 @@ Alphabetical list of modules:
    figure_api.rst
    font_manager_api.rst
    fontconfig_pattern_api.rst
+   ft2font.rst
    gridspec_api.rst
    hatch_api.rst
    image_api.rst
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -1579,7 +1579,7 @@ def _cached_realpath(path):
 @_api.rename_parameter('3.6', "filepath", "font_filepaths")
 def get_font(font_filepaths, hinting_factor=None):
     """
-    Get an ``ft2font.FT2Font`` object given a list of file paths.
+    Get an `.ft2font.FT2Font` object given a list of file paths.
 
     Parameters
     ----------
@@ -1595,7 +1595,7 @@ def get_font(font_filepaths, hinting_factor=None):
 
     Returns
     -------
-    ``ft2font.FT2Font``
+    `.ft2font.FT2Font`
 
     """
     if isinstance(font_filepaths, (str, Path, bytes)):
diff --git a/src/ft2font_wrapper.cpp b/src/ft2font_wrapper.cpp
@@ -310,10 +310,24 @@ static PyObject *PyFT2Font_new(PyTypeObject *type, PyObject *args, PyObject *kwd
 }
 
 const char *PyFT2Font_init__doc__ =
-    "FT2Font(ttffile)\n"
+    "FT2Font(filename, hinting_factor=8, *, _fallback_list=None, _kerning_factor=0)\n"
     "--\n\n"
     "Create a new FT2Font object.\n"
     "\n"
+    "Parameters\n"
+    "----------\n"
+    "filename : str or file-like\n"
+    "    The source of the font data in a format (ttf or ttc) that FreeType can read\n\n"
+    "hinting_factor : int, optional\n"
+    "    Must be positive. Used to scale the hinting in the x-direction\n"
+    "_fallback_list : list of FT2Font, optional\n"
+    "    A list of FT2Font objects used to find missing glyphs.\n\n"
+    "    .. warning ::\n"
+    "        This API is both private and provisional: do not use it directly\n\n"
+    "_kerning_factor : int, optional\n"
+    "    Used to adjust the degree of kerning.\n\n"
+    "    .. warning ::\n"
+    "        This API is private: do not use it directly\n\n"
     "Attributes\n"
     "----------\n"
     "num_faces\n"
@@ -518,10 +532,10 @@ const char *PyFT2Font_get_kerning__doc__ =
     "get_kerning(self, left, right, mode)\n"
     "--\n\n"
     "Get the kerning between *left* and *right* glyph indices.\n"
-    "*mode* is a kerning mode constant:\n"
-    "  KERNING_DEFAULT  - Return scaled and grid-fitted kerning distances\n"
-    "  KERNING_UNFITTED - Return scaled but un-grid-fitted kerning distances\n"
-    "  KERNING_UNSCALED - Return the kerning vector in original font units\n";
+    "*mode* is a kerning mode constant:\n\n"
+    "    - KERNING_DEFAULT  - Return scaled and grid-fitted kerning distances\n"
+    "    - KERNING_UNFITTED - Return scaled but un-grid-fitted kerning distances\n"
+    "    - KERNING_UNSCALED - Return the kerning vector in original font units\n";
 
 static PyObject *PyFT2Font_get_kerning(PyFT2Font *self, PyObject *args)
 {
@@ -626,16 +640,16 @@ const char *PyFT2Font_load_char__doc__ =
     "Load character with *charcode* in current fontfile and set glyph.\n"
     "*flags* can be a bitwise-or of the LOAD_XXX constants;\n"
     "the default value is LOAD_FORCE_AUTOHINT.\n"
-    "Return value is a Glyph object, with attributes\n"
-    "  width          # glyph width\n"
-    "  height         # glyph height\n"
-    "  bbox           # the glyph bbox (xmin, ymin, xmax, ymax)\n"
-    "  horiBearingX   # left side bearing in horizontal layouts\n"
-    "  horiBearingY   # top side bearing in horizontal layouts\n"
-    "  horiAdvance    # advance width for horizontal layout\n"
-    "  vertBearingX   # left side bearing in vertical layouts\n"
-    "  vertBearingY   # top side bearing in vertical layouts\n"
-    "  vertAdvance    # advance height for vertical layout\n";
+    "Return value is a Glyph object, with attributes\n\n"
+    "- width          # glyph width\n"
+    "- height         # glyph height\n"
+    "- bbox           # the glyph bbox (xmin, ymin, xmax, ymax)\n"
+    "- horiBearingX   # left side bearing in horizontal layouts\n"
+    "- horiBearingY   # top side bearing in horizontal layouts\n"
+    "- horiAdvance    # advance width for horizontal layout\n"
+    "- vertBearingX   # left side bearing in vertical layouts\n"
+    "- vertBearingY   # top side bearing in vertical layouts\n"
+    "- vertAdvance    # advance height for vertical layout\n";
 
 static PyObject *PyFT2Font_load_char(PyFT2Font *self, PyObject *args, PyObject *kwds)
 {
@@ -664,16 +678,16 @@ const char *PyFT2Font_load_glyph__doc__ =
     "Load character with *glyphindex* in current fontfile and set glyph.\n"
     "*flags* can be a bitwise-or of the LOAD_XXX constants;\n"
     "the default value is LOAD_FORCE_AUTOHINT.\n"
-    "Return value is a Glyph object, with attributes\n"
-    "  width          # glyph width\n"
-    "  height         # glyph height\n"
-    "  bbox           # the glyph bbox (xmin, ymin, xmax, ymax)\n"
-    "  horiBearingX   # left side bearing in horizontal layouts\n"
-    "  horiBearingY   # top side bearing in horizontal layouts\n"
-    "  horiAdvance    # advance width for horizontal layout\n"
-    "  vertBearingX   # left side bearing in vertical layouts\n"
-    "  vertBearingY   # top side bearing in vertical layouts\n"
-    "  vertAdvance    # advance height for vertical layout\n";
+    "Return value is a Glyph object, with attributes\n\n"
+    "- width          # glyph width\n"
+    "- height         # glyph height\n"
+    "- bbox           # the glyph bbox (xmin, ymin, xmax, ymax)\n"
+    "- horiBearingX   # left side bearing in horizontal layouts\n"
+    "- horiBearingY   # top side bearing in horizontal layouts\n"
+    "- horiAdvance    # advance width for horizontal layout\n"
+    "- vertBearingX   # left side bearing in vertical layouts\n"
+    "- vertBearingY   # top side bearing in vertical layouts\n"
+    "- vertAdvance    # advance height for vertical layout\n";
 
 static PyObject *PyFT2Font_load_glyph(PyFT2Font *self, PyObject *args, PyObject *kwds)
 {
