Separate harfbuzz API wrappers from our own functions

[simoncozens]

Now we have draw_glyph_with_pen this library is no longer a plain wrapper around the Harfbuzz API. I suggest we move uharfbuzz unique functions to a separate Python file where they can be documented. My Cython-fu is not good enough to know how to do this.

[anthrotype]

you could either add a pure-python module for the wrappers (but then you can only use pure-python import, not any Cython or C++ types), or you could add a new .pyx cython module inside src/uharfbuzz containing your new wrappers, then you also need to create a _harfbuzz.pxd and move there all the cdef Cython declarations in the current _harbuzz.pyx so that other Cython modules (like the one you're adding) can cimport them, see https://cython.readthedocs.io/en/latest/src/userguide/sharing_declarations.html

Also, in setup.py you pass the filename of your new .pyx module to cythonize function (which can take a list of .pyx filenames or distutils Extension classes)

diff --git a/setup.py b/setup.py
index 8a9bab8..38211c0 100755
--- a/setup.py
+++ b/setup.py
@@ -23,14 +23,17 @@ extra_compile_args = []
 if platform.system() != 'Windows':
     extra_compile_args.append('-std=c++11')

-extension = Extension(
-    'uharfbuzz._harfbuzz',
-    define_macros=define_macros,
-    include_dirs=['harfbuzz/src'],
-    sources=['src/uharfbuzz/_harfbuzz.pyx', 'harfbuzz/src/harfbuzz.cc'],
-    language='c++',
-    extra_compile_args=extra_compile_args,
-)
+cython_modules = [
+    Extension(
+        'uharfbuzz._harfbuzz',
+        define_macros=define_macros,
+        include_dirs=['harfbuzz/src'],
+        sources=['src/uharfbuzz/_harfbuzz.pyx', 'harfbuzz/src/harfbuzz.cc'],
+        language='c++',
+        extra_compile_args=extra_compile_args,
+    ),
+    "src/uharfbuzz/foobar.pyx",
+]

 setup(
     name="uharfbuzz",
@@ -48,7 +51,7 @@ setup(
     setup_requires=["setuptools_scm"],
     python_requires=">=3.5",
     ext_modules = cythonize(
-        extension,
+        cython_modules,
         annotate=bool(int(os.environ.get('CYTHON_ANNOTATE', '0'))),
         compiler_directives={"linetrace": linetrace},
     ),

[khaledhosny]

Is the of documentation the issue here? Can’t we document Cython code?