Generate and publish latest documentation (probably migrating from jazzy to docc)

[michaelkirk]

Motivation

I wanted to browse the latest API docs for maplibre-navigation-ios, but couldn't find any prebuilt. It looks like there is configuration for building docs via jazzy, but I haven't found any evidence of published documentation for malibre-navigation-ios yet.

In maplibre-native, jazzy has been succeeded by docc (issue: maplibre/maplibre-native#676)

Presumably we want to do the same thing here.

Design Alternatives

We could stay with Jazzy or pick some other documentation provider, but it seems like all the same logic in #676 applies here.

We could continue not to publish pre-built docs and have developers browse documentation in the source files, but I think it's worth going through the effort of pre-building docs and publishing it for all the same reasons anyone does this anywhere.

Design

Use cases:

• CI will build docs
• CI will publish docs
• Local dev should be able to build docs for their own usage
• Local dev should be able to build docs to preview their documentation changes

Mock-Up

I'm assuming we'll use whatever documentation style is used by maplibre-native (or the default style)

Concepts

n/a

Implementation

• Add a script like https://github.com/maplibre/maplibre-native/blob/main/platform/ios/scripts/docc.sh to build the docs
• Add a section in the README about how to build the docs (doc docs)
• Add a CI job that builds the docs every commit to make sure docs are always buildable.
• Add a CI job that published the docs every (tag?) to GH pages to make sure docs for published release are available
• Link to latest (latest main?/ latest tag?) docs on maplibre.org

[michaelkirk]

Currently, swift package generate-documentation fails: https://github.com/michaelkirk/maplibre-navigation-ios/actions/runs/9358227464/job/25759607313?pr=1#step:4:148

The error is:

In file included from /Users/runner/work/maplibre-navigation-ios/maplibre-navigation-ios/MapboxNavigationObjC/MLNMapView+MLNNavigationAdditions.m:1:
/Users/runner/work/maplibre-navigation-ios/maplibre-navigation-ios/MapboxNavigationObjC/MLNMapView+MLNNavigationAdditions.h:1:9: fatal error: 'MapLibre/Mapbox.h' file not found
#import <MapLibre/Mapbox.h>
        ^~~~~~~~~~~~~~~~~~~
1 error generated.
[25/93] Compiling MapboxNavigationObjC MLNMapView+MLNNavigationAdditions.m
[25/93] Compiling MapboxNavigationObjC MBRouteVoiceController.m
error: unspecified("fatalError")
Generating documentation for 'MapboxNavigation'...

I'm still pretty new to swift package manager. I've noticed though that xcode does not list any of the MapLibre headers under the dependency (e.g. compare the filetree under MapLibre to that of Polyline):

Maybe that's related to the header not being found by the documentation generator.