Add Mapbox Jazzy theme

[friedbunny]

Based on Jazzy's fullwidth theme.

To-do

This is a good start, but there are more improvements to be made:

• Truncate long method names in the nav and lists, when necessary.
• Update the screenshot triptych with new shots and frames.
• Bring in Open Sans as the font, like Mapbox.com.
• Hide empty/broken “Other Type Definitions” section. "Other Type Definitions" link is a 404 #3957
• Report broken Swift method parsing upstream. Problem with generating Swift declarations from Objective-C realm/jazzy#536
• Force minimum navigation bar width (Chrome is misbehaving).
• Better wrap~~/truncate~~ long methods on class pages.
• Add theme to macOS jazzy docs, too.

Going forward

Jazzy allows for arbitrary prose sections written in Markdown that include the same code highlighting, so we could even consider moving the examples or guides into here, too. This could be a good opportunity to write specific feature sections that focus on complex features such as offline or annotations.

Main page

First draft.

MGLMapView

First draft.

/cc @danswick @1ec5 @cammace @boundsj @frederoni

[1ec5]

Hide empty/broken “Other Type Definitions” section.

#3957

[1ec5]

Jazzy allows for arbitrary prose sections written in Markdown that include the same code highlighting, so we could even consider moving the examples or guides into here, too.

That’s realm/jazzy#435, released just a few hours ago in jazzy 0.6.3 (upgrade now!). I’m strongly in favor of doing this, because it makes our examples that much more discoverable to Dash users. The examples would likely be maintained in this repository, where the broader community can help maintain and expand them. Also, it would allow us to eventually replace the entire /ios-sdk site with the jazzy documentation (with an online-specific readme, perhaps), streamlining navigation considerably.

[friedbunny]

Ellipsized extra-long navigation items, though I believe @1ec5 disapproves of my methods. 😁

[friedbunny]

realm/jazzy#590 may fix #3957.

[friedbunny]

Going to give this Jazzy theme another look after evaluating the new Apple documentation style, see if there’s anything to borrow.

[friedbunny]

SourceKit is the cause of UnsafeMutablePointer swallowing the rest of the method signature, per realm/jazzy#536. No up-upstream issue exists yet.

This is where the problem manifests for us: when we use a pointer to a struct, such as in -[MGLMapView setVisibleCoordinates:count:edgePadding:animated:] with CLLocationCoordinate2D:

- (void)setVisibleCoordinates:(CLLocationCoordinate2D *)coordinates count:(NSUInteger)count edgePadding:(UIEdgeInsets)insets animated:(BOOL)animated;

[friedbunny]

Made this more Mapboxy by using Open Sans for the text — screencaps have been updated. (Though, Paparazzi doesn’t seem to do a good job rendering... some link colors are off, smallcaps isn’t working, and some SVGs are weird. Oh well.)

[friedbunny]

Rebased and squashed this down to the essential commits. The iOS screenshot is still a placeholder, pending me actually coming up with something that decently illustrates polylines.

Also added macOS support:

... had to fake a macos tag in order for it to build.

[cammace]

Wow this looks great @friedbunny, can't wait to see it live!

[1ec5]

Don’t forget to note the new design in the changelog for both SDKs!

[friedbunny]

[friedbunny]

For anyone wanting to update the iOS screenshots, there’s a new Sketch file at platform/ios/originals/screenshots.sketch that includes the frame and images.