From 6c991dfc02a5b1e7bdedbc2cbcc53f192da03a50 Mon Sep 17 00:00:00 2001 From: Hoolean Date: Sun, 22 Sep 2024 11:57:06 +0100 Subject: [PATCH 1/6] Add API reference generated by Sphinx This is `sphinx-quickstart` as modified to automatically produce documentation for the module, taking a few hints from fonttools/ufoLib2 to inform structure, build workflow, and styling. --- docs/.gitignore | 1 + docs/source/conf.py | 25 +++++++++++++++++++++++++ docs/source/index.rst | 11 +++++++++++ docs/source/reference.rst | 7 +++++++ tox.ini | 9 +++++++++ 5 files changed, 53 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/reference.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..f3d6549 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +/build/ \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..9651d2e --- /dev/null +++ b/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 = "Adrien Tétar" + +# -- 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" diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..7764e0a --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,11 @@ +uharfbuzz documentation +======================= + +.. include:: ../../README.md + :parser: myst_parser.sphinx_ + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + reference diff --git a/docs/source/reference.rst b/docs/source/reference.rst new file mode 100644 index 0000000..1e01242 --- /dev/null +++ b/docs/source/reference.rst @@ -0,0 +1,7 @@ +API Reference +============= + +.. automodule:: uharfbuzz + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/tox.ini b/tox.ini index 028d7c2..40ab578 100644 --- a/tox.ini +++ b/tox.ini @@ -63,6 +63,15 @@ 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 = + Sphinx >= 7.4.7 + sphinx-rtd-theme >= 2.0.0 + myst-parser >= 4.0.0 +commands = + sphinx-build -j auto docs/source/ docs/build/ + [pytest] testpaths = tests/ addopts = From 73edc815fd6f083c2ff8b92ad5ef7de60c35fbef Mon Sep 17 00:00:00 2001 From: Hoolean Date: Sun, 22 Sep 2024 11:59:55 +0100 Subject: [PATCH 2/6] Restrict star-exports to objects defined in this module Having an explicit __all__ is necessary to avoid re-exporting objects that we ourselves have imported (e.g. from the standard library). This also helps avoid objects that this project did not author from appearing in the automatically generated Sphinx documentation. This list was generated by: ```python import uharfbuzz print(dir(uharfbuzz)) ``` ...before being manually pruned. --- src/uharfbuzz/__init__.py | 92 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/src/uharfbuzz/__init__.py b/src/uharfbuzz/__init__.py index 32b583a..3afe9ff 100644 --- a/src/uharfbuzz/__init__.py +++ b/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", +] From c92572abc1e50f86ba183c1755babe164a183274 Mon Sep 17 00:00:00 2001 From: Hoolean Date: Tue, 24 Sep 2024 22:01:21 +0100 Subject: [PATCH 3/6] Change author based on PR feedback See #212 --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 9651d2e..461ed4a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -9,7 +9,7 @@ project = "uharfbuzz" copyright = "2024, Adrien Tétar" -author = "Adrien Tétar" +author = "HarfBuzz Contributors" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration From 4d02b4be6f297e4ab755b6d21676b65596c9cb91 Mon Sep 17 00:00:00 2001 From: Hoolean Date: Tue, 24 Sep 2024 22:34:58 +0100 Subject: [PATCH 4/6] Pin Sphinx requirements for reproducible builds This is following the guidance at: https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html ...in preparation for adding Read the Docs build support, where having an explicit requirements.txt file to point to will also be helpful. --- docs/requirements.in | 3 ++ docs/requirements.txt | 73 +++++++++++++++++++++++++++++++++++++++++++ tox.ini | 6 ++-- 3 files changed, 78 insertions(+), 4 deletions(-) create mode 100644 docs/requirements.in create mode 100644 docs/requirements.txt diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 0000000..a00fbc4 --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,3 @@ +Sphinx >= 7.4.7 +sphinx-rtd-theme >= 2.0.0 +myst-parser >= 4.0.0 \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..6580990 --- /dev/null +++ b/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 diff --git a/tox.ini b/tox.ini index 40ab578..dfdecb3 100644 --- a/tox.ini +++ b/tox.ini @@ -65,10 +65,8 @@ commands = [testenv:docs] description = build Sphinx docs, including API reference -deps = - Sphinx >= 7.4.7 - sphinx-rtd-theme >= 2.0.0 - myst-parser >= 4.0.0 +deps = -r{toxinidir}/docs/requirements.txt +changedir = {toxinidir} commands = sphinx-build -j auto docs/source/ docs/build/ From 38ef9e859b4d05204fcab4e279fd7a33a5173d2d Mon Sep 17 00:00:00 2001 From: Hoolean Date: Tue, 24 Sep 2024 22:37:59 +0100 Subject: [PATCH 5/6] Add Read the Docs configuration file This is based on the Sphinx reference config file here: https://docs.readthedocs.io/en/stable/config-file/v2.html#python-install ...with some trimming, customisation for the project, and additional adjustments recommended for reproducible builds. --- .readthedocs.yml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .readthedocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..31f1d5a --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,25 @@ +# 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 From dcf7c276578725094e8321b85f849307b6c79bec Mon Sep 17 00:00:00 2001 From: Hoolean Date: Tue, 24 Sep 2024 22:41:27 +0100 Subject: [PATCH 6/6] Install self as package to facilitate API reference discovery --- .readthedocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 31f1d5a..232b123 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -23,3 +23,6 @@ sphinx: python: install: - requirements: docs/requirements.txt + - requirements: requirements.txt + - method: pip + path: .