Find a way to document freetype and windows-specific code

[djhoese]

Certain parts of aggdraw are only available if running/built on Windows or if aggdraw was built with freetype support. Right now I'm making aggdraw docs on readthedocs which is not as easy to accomplish this stuff with. I see two options:

1. Generate documentation on travis/appveyor (that would mean building on Windows with freetype).
2. Manually copy/document those pieces of the package in the .rst files.

[a-hurst]

Just wanted to mention that I might have a solution for including FreeType in the Windows wheels (which would solve this issue), though I won't have the time to test it out anytime soon: it looks like the freetype-py project has a build script for building FreeType on Windows that works with Appveyor, meaning that we could either adapt this code for aggdraw or alternatively just produce x86/x64 Windows FreeType DLLs using the script that we can then use for building aggdraw on Appveyor. We'd also need some code for bundling the .dll with the wheel (since there's no package to do this automatically like there is on macOS or Linux), but there are plenty of examples of other projects doing this that we could follow.

[djhoese]

What about just depending on freetype-py?

Edit: And building against it when the wheels are generated, if needed.

[a-hurst]

That could work, but the built .dlls are buried within the wheels so building aggdraw wheels against it might be difficult. We could also just set up the appveyor CI to download and extract the .dll from the freetype-py wheel and then include that in the Windows wheels, which would likely be easier to implement while still keeping aggdraw dependency-free.

[djhoese]

I'm not really familiar with linking when it comes to .dll's. If we can install freetype-py and point the AGGDRAW_FREETYPE_ROOT environment variable where its .dll is, then that's probably the best overall solution. Oh wait...that wouldn't provide the headers needed for building. Could we modify the setup.py to point at a system installed freetype for the headers and then point to the freetype-py .dll...no that's a terrible idea.

I'm not sure your suggestion would work either since we need the freetype headers.

[a-hurst]

Hmm, good point. Depending on how much it slows the builds, maybe integrating the build script is the best solution. Shame Windows doesn't have a package manager that would make getting the binaries/headers as easy as it is on Linux/macOS...

[djhoese]

I think the astropy/ci-helpers project uses "Chocolatey"?

Edit: https://chocolatey.org/

[a-hurst]

Yeah I've looked at that in the past, but it's missing a lot of development libraries (including freetype, sadly). I was recently made aware of a C/C++ package manager called Conan which looks like it does support freetype, but it seems complicated to set up and looks like it still requires you to build everything from source.

[a-hurst]

Look like we might have a new contender here: Microsoft, of all places, has apparently come up with a cross-platform package manager called vcpkg that builds/installs the binaries and headers for lots of common libraries (including Freetype) with a single terminal command (e.g. vcpkg install freetype).

Apparently it's already pre-installed on all Appveyor images and supports both 32-bit and 64-bit Windows, so if it works, the only thing we'd need to do would be to copy its pre-built binary into the wheels somewhere and make sure that aggdraw can actually link to it. Over the holidays I'm going to try and figure out if vcpkg can help me get bundled .dlls for pysdl2 fully working, so if I'm successful I can hopefully apply what I've learned here, too.