Add API reference generated by Sphinx

.readthedocs.yml

@@ -0,0 +1,28 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  # Fail on all warnings to avoid broken references
+  # TODO: Enable after README and repack_with_tag() warnings are corrected
+  # fail_on_warning: true
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: docs/requirements.txt
+  - requirements: requirements.txt
+  - method: pip
+    path: .

docs/.gitignore

@@ -0,0 +1 @@
+/build/

docs/requirements.in

@@ -0,0 +1,3 @@
+Sphinx >= 7.4.7
+sphinx-rtd-theme >= 2.0.0
+myst-parser >= 4.0.0

docs/requirements.txt

@@ -0,0 +1,73 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+alabaster==0.7.16
+    # via sphinx
+babel==2.16.0
+    # via sphinx
+certifi==2024.8.30
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+docutils==0.20.1
+    # via
+    #   myst-parser
+    #   sphinx
+    #   sphinx-rtd-theme
+idna==3.10
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.4
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+markupsafe==2.1.5
+    # via jinja2
+mdit-py-plugins==0.4.2
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==4.0.0
+    # via -r requirements.in
+packaging==24.1
+    # via sphinx
+pygments==2.18.0
+    # via sphinx
+pyyaml==6.0.2
+    # via myst-parser
+requests==2.32.3
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==7.4.7
+    # via
+    #   -r requirements.in
+    #   myst-parser
+    #   sphinx-rtd-theme
+    #   sphinxcontrib-jquery
+sphinx-rtd-theme==2.0.0
+    # via -r requirements.in
+sphinxcontrib-applehelp==2.0.0
+    # via sphinx
+sphinxcontrib-devhelp==2.0.0
+    # via sphinx
+sphinxcontrib-htmlhelp==2.1.0
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==2.0.0
+    # via sphinx
+sphinxcontrib-serializinghtml==2.0.0
+    # via sphinx
+urllib3==2.2.3
+    # via requests

docs/source/conf.py

@@ -0,0 +1,25 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "uharfbuzz"
+copyright = "2024, Adrien Tétar"
+author = "HarfBuzz Contributors"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "myst_parser",
+]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"

docs/source/index.rst

@@ -0,0 +1,11 @@
+uharfbuzz documentation
+=======================
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   reference

docs/source/reference.rst

@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. automodule:: uharfbuzz
+    :members:
+    :undoc-members:
+    :show-inheritance:

src/uharfbuzz/__init__.py

@@ -4,3 +4,95 @@
     __version__ = "0.0.0+unknown"
 
 from ._harfbuzz import *
+
+__all__ = [
+    "Blob",
+    "Buffer",
+    "BufferClusterLevel",
+    "BufferContentType",
+    "BufferFlags",
+    "Color",
+    "ColorLine",
+    "ColorStop",
+    "DrawFuncs",
+    "Face",
+    "Font",
+    "FontExtents",
+    "FontFuncs",
+    "GlyphExtents",
+    "GlyphFlags",
+    "GlyphInfo",
+    "GlyphPosition",
+    "HBObject",
+    "HarfBuzzError",
+    "Map",
+    "MapIter",
+    "OTColor",
+    "OTColorLayer",
+    "OTColorPalette",
+    "OTColorPaletteFlags",
+    "OTLayoutGlyphClass",
+    "OTMathConstant",
+    "OTMathGlyphPart",
+    "OTMathGlyphPartFlags",
+    "OTMathGlyphVariant",
+    "OTMathKern",
+    "OTMathKernEntry",
+    "OTMetricsTag",
+    "OTVarAxisFlags",
+    "OTVarAxisInfo",
+    "OTVarNamedInstance",
+    "PaintCompositeMode",
+    "PaintExtend",
+    "PaintFuncs",
+    "RepackerError",
+    "Set",
+    "SetIter",
+    "SubsetFlags",
+    "SubsetInput",
+    "SubsetInputSets",
+    "SubsetPlan",
+    "__version__",
+    "ot_color_glyph_get_layers",
+    "ot_color_glyph_get_png",
+    "ot_color_glyph_get_svg",
+    "ot_color_glyph_has_paint",
+    "ot_color_has_layers",
+    "ot_color_has_paint",
+    "ot_color_has_palettes",
+    "ot_color_has_png",
+    "ot_color_has_svg",
+    "ot_color_palette_color_get_name_id",
+    "ot_color_palette_get_colors",
+    "ot_color_palette_get_count",
+    "ot_color_palette_get_flags",
+    "ot_color_palette_get_name_id",
+    "ot_font_set_funcs",
+    "ot_layout_get_baseline",
+    "ot_layout_get_glyph_class",
+    "ot_layout_has_glyph_classes",
+    "ot_layout_has_positioning",
+    "ot_layout_has_substitution",
+    "ot_layout_language_get_feature_tags",
+    "ot_layout_lookup_get_glyph_alternates",
+    "ot_layout_script_get_language_tags",
+    "ot_layout_table_get_script_tags",
+    "ot_math_get_constant",
+    "ot_math_get_glyph_assembly",
+    "ot_math_get_glyph_italics_correction",
+    "ot_math_get_glyph_kerning",
+    "ot_math_get_glyph_kernings",
+    "ot_math_get_glyph_top_accent_attachment",
+    "ot_math_get_glyph_variants",
+    "ot_math_get_min_connector_overlap",
+    "ot_math_has_data",
+    "ot_math_is_glyph_extended_shape",
+    "ot_tag_to_language",
+    "ot_tag_to_script",
+    "repack",
+    "repack_with_tag",
+    "shape",
+    "subset",
+    "subset_preprocess",
+    "version_string",
+]

tox.ini

@@ -63,6 +63,13 @@ commands =
     python -c 'import os, glob; whl = glob.glob(".tox/dist/*.whl"); whl and os.remove(whl[0])'
     pip wheel --pre --no-deps --no-cache-dir --wheel-dir {distdir} --find-links {distdir} --no-binary {[tox]project_name} {[tox]project_name}
 
+[testenv:docs]
+description = build Sphinx docs, including API reference
+deps = -r{toxinidir}/docs/requirements.txt
+changedir = {toxinidir}
+commands =
+    sphinx-build -j auto docs/source/ docs/build/
+
 [pytest]
 testpaths = tests/
 addopts =