Guides for style and GeoJSON authors

[1ec5]

Added two guides to the jazzy documentation:

• “Working with GeoJSON Data” maps GeoJSON concepts and types to the runtime styling API.
• “Information for Style Authors” points out a number of tips for designing a style appropriate for an iOS or macOS application and also maps style JSON types to the runtime styling API to help Mapbox Studio users. This document is generated by make style-code-darwin just like the rest of the runtime styling API. I avoided talking in great detail about Studio or the runtime styling API to avoid overlapping with [ios] Adds guides to documentation sidebar #7488.

These two guides are shared between the iOS and macOS docsets. This means the iOS SDK documentation will include some language specific to macOS and vice versa. I think this is fine, given that Apple’s own guides do the same thing. The two guides are now separate but generated from the same template.

Fixes #7530.

/cc @friedbunny @ericrwolfe @mapbox/copycop

[mention-bot]

@1ec5, thanks for your PR! By analyzing this pull request, we identified @incanus, @boundsj and @friedbunny to be potential reviewers.

[1ec5]

These guides highlight the need for autolinking in guides and the readme: realm/jazzy#715.

[1ec5]

“Working with GeoJSON Data”

“Information for Style Authors” (iOS)

“Information for Style Authors” (macOS)

[1ec5]

The “Information for Style Authors” guide now comes in two flavors, one for iOS and one for macOS. Both are compiled from the same template. I’ve updated the screenshots above to reflect the split.

[ericrwolfe]

Rebased atop the current release branch including #7488.

[ericrwolfe]

These are both useful in bridging the gap in understanding between the GeoJSON spec and the Mapbox Style spec 👍.

We ought to consider moving some of the content from For Style Authors.md out into the respective source documentation headers and link out from the guide, at least until auto linking in jazzy improves.

[1ec5]

We ought to consider moving some of the content from For Style Authors.md out into the respective source documentation headers and link out from the guide, at least until auto linking in jazzy improves.

realm/jazzy#715 is high on the 👊 list. We do mention most (if not all) of the information contained in the tables in the far-flung parts of the API reference, at least where there’s a difference. If you see anything that should be duplicated in the reference pages, please let me know.

In compiling these documents, I wanted to take into consideration @tmcw’s concern that someone familiar with Studio or GL JS would have no good starting point to apply their existing knowledge to the SDK or infer some of the more systematic differences in terminology or typing. The table of contents could be bewildering for these developers, despite your much-needed rework of it, especially when it comes to the source options.

[1ec5]

These guides are located in platform/ios/docs/guides/, so they aren’t available to the macOS SDK. While most of the Runtime Styling and Working with Mapbox Studio guides apply equally to the macOS SDK, some of the screenshots would need to be substituted with macOS screenshots, and the “Adding Points to a Map” guide discusses view-backed annotations, which have yet to be implemented on macOS: #5035.

Let’s leave these guides out for now. We can figure out how to bring them over to the macOS SDK in a separate PR. Maybe we should think at that point about whether any of this great content could be reused in Android SDK documentation as well.

[1ec5]

I edited the filter-to-predicate-format table to show how multiple values are handled in the format string (especially none to NOT (… OR …)):

[nitrag]

@friedbunny The URL for beta 7 docs is broken. Thanks for the prerelease!
https://www.mapbox.com/ios-sdk/api/3.4.0-beta.7/

[1ec5]

It’s up now, @nitrag.

Here are the guides added by this PR:

https://www.mapbox.com/ios-sdk/api/3.4.0-beta.7/working-with-geojson-data.html
https://www.mapbox.com/ios-sdk/api/3.4.0-beta.7/for-style-authors.html

[friedbunny]

It’s up now

Well, as soon as it finishes publishing — give it a minute or two. 😉

The delay came from the fact that we finished building late last night and the jazzy generation process is slightly more involved than usual, as we make improvements in the betas.