iOS jazzy theme small improvements #7422

mayagao · 2016-12-14T03:19:50Z

Some small problems:

No limiter for the content, expand infinitely on large screens.
Links are not obvious in the code
some fonts too small and a bit hard to read
not obvious some links are expandable

Sketch:

overall polish the styles a bit, make the code more distinguishable from normal text

Current status:

still work in progress

cc @friedbunny

mention-bot · 2016-12-14T03:19:51Z

@mayagao, thanks for your PR! By analyzing this pull request, we identified @friedbunny to be potential reviewers.

friedbunny · 2016-12-14T19:21:41Z

This looks great, thanks for all of the additional polish. I’ve retargeted this PR against the release branch and I’ll help you rebase it so that the extra commits go away.

I noticed that the new collapse/minus button has an extra bit of button following it on Safari:

friedbunny · 2016-12-15T00:37:54Z

/cc @mapbox/ios

1ec5

This theme has come a long way! I’m excited about getting it in, especially for the usability improvement of making links easier to spot.

Below are a number of comments related to the design. Most are optional – things I just noticed because I’ve never scrutinized the design to this extent before. The only piece of feedback I’d consider essential is the bit about keeping the {{module_name}} placeholder in the header instead of hard-coding the product name.

By the way, if you need any help understanding the use or relative importance of any element in this documentation, please feel free to ask.

1ec5 · 2016-12-15T09:00:34Z

platform/darwin/docs/theme/templates/header.mustache

+    <p class="header-col header-col--primary">
+      <a class="header-link" href="{{path_to_root}}index.html">
+        <img style="height: 25px;"  class="header-icon" src="{{path_to_root}}img/mapbox.svg" alt="{{module_name}} Docs"/>
+        <span class='header-tag'>iOS SDK Reference</span>


These templates are used for both the iOS SDK and macOS SDK. Keep {{module_name}} here; document.sh replaces “Mapbox Reference” with “Mapbox iOS SDK Reference” or “Mapbox macOS SDK Reference” as appropriate. realm/jazzy#411 tracks making this name configurable outside the template.

emm when I use {{module_name}} it only shows mapbox, not mapbox reference

It’ll show “Mapbox” if you run jazzy directly. However, if you run make idocument or make xdocument, document.sh will automatically correct the name to “Mapbox iOS SDK” or “Mapbox macOS SDK”. (This is how “Mapbox iOS SDK Reference” shows up in the current online documentation, for example.)

You do have to append “Docs” or “Reference” after {{module_name}}, because the script looks specifically for the phrases “Mapbox Docs” and “Mapbox Reference”.

ahhh ok fixed

1ec5 · 2016-12-15T09:09:11Z

platform/darwin/docs/theme/assets/css/jazzy.css.scss

+    background: $color_light;
+    padding: 0.1em 0.2em;
+    font-weight: bold;
+    border: 1px solid #D5D5D5;


This border, combined with the padding and boldfacing, gives each <code> tag too much weight, breaking up the flow in prose. Even unlinked <code> tags look like links:

Toning it down a bit would probably be fine, but I do like that there’s more emphasis on the inline code blocks now.

1ec5 · 2016-12-15T09:23:34Z

platform/darwin/docs/theme/assets/css/jazzy.css.scss

@@ -488,9 +536,16 @@ pre code {
 }

 .language {
+  background: $color_light;


Subtly color-coding the two languages is a good idea. I’ll have to consult with you when I add AppleScript code snippets to the macOS SDK documentation. 😉 On the other hand, perhaps we should take this opportunity to add a language toggle to make this color-coding unnecessary: #7448.

Let’s wait on the #7448 toggle, so that this is sure to get into v3.4.0.

1ec5 · 2016-12-15T09:26:33Z

platform/darwin/docs/theme/templates/nav.mustache

@@ -2,7 +2,7 @@
  <ul class="nav-groups">
    {{#structure}}
    <li class="nav-group-name">
-      <a class="nav-group-name-link" href="{{path_to_root}}{{section}}.html">{{section}}</a>
+      <a class="small-heading" href="{{path_to_root}}{{section}}.html">{{section}}</a>
      <ul class="nav-group-tasks">
        {{#children}}
        <li class="nav-group-task">


Lots of function names overflow no matter how wide we make the table of contents, and this issue worsens as the window narrows:

We can mitigate this issue by attaching title attributes to each of the links.

1ec5 · 2016-12-15T09:30:01Z

platform/darwin/docs/theme/assets/css/jazzy.css.scss

  border-collapse: collapse;
  border-spacing: 0;
  overflow: auto;
  margin: 0 0 0.85em;
 }

-tr {
-  &:nth-child(2n) {
-    background-color: $table_alt_row_color;


You don’t like the zebra striping? 😄 I thought it rather nice, but I agree that it’s unnecessary given the horizontal rules.

1ec5 · 2016-12-15T09:32:54Z

platform/darwin/docs/theme/assets/css/jazzy.css.scss

@@ -406,10 +438,7 @@ pre code {
  }
 }

-.item-container { }
-
 .item {


The hit target for auto-expanding section links hugs the text too closely, making it difficult to click the link. Any chance we could increase the padding around these links, without necessarily spacing the links farther apart?

1ec5 · 2016-12-15T09:33:51Z

platform/darwin/docs/theme/templates/task.mustache

-              show on github
-              <img class="show-on-github-icon" src="{{{path_to_root}}}img/github.svg"/>
+              <img style="margin-bottom: 1px;" class="show-on-github-icon" src="{{{path_to_root}}}img/github.svg"/>
+              View Source on Github


Since this text is no longer all in lowercase, please capitalize “Github” as “GitHub”.

1ec5 · 2016-12-15T09:39:00Z

platform/darwin/docs/theme/assets/css/jazzy.css.scss

@@ -538,6 +599,16 @@ pre code {
  padding-left: 2px;
 }

+.show-on-github a {
+  padding: 0px 5px;
+  background: rgba(56, 135, 190, 0.12);


This makes the “View Source on GitHub” link much more prominent than before. While I like the treatment, it may cause these links to call too much attention to themselves. Unlike with GL JS, these links only go to the declaration and documentation comment for the symbol – the exact same thing as the content right above the link, except set in a monospaced font and wrapped at 80 columns. As far as I can tell, the main use case for these links is for code contributors to easily get to the relevant header to correct typos.

1ec5 · 2016-12-15T09:42:09Z

platform/darwin/docs/theme/assets/css/jazzy.css.scss

 th, td {
  padding: 6px 13px;
-  border: 1px solid $table_border_color;
+  border: 1px solid $keyline_color;


Since this documentation is most likely to be viewed on Retina displays, we can also use darker, half-pixel-wide borders to achieve a crisper look without sacrificing subtlety.

1ec5 · 2016-12-15T09:56:39Z

This PR also introduces a couple regressions in terms of responsive design, which was never great to begin with. As a stress test, here’s a before and after of the documentation at the resolution of an iPhone 5s or iPhone SE:

I’m ambivalent about it, but the expandable section names don’t wrap, so they scroll quite far horizontally on a narrow screen while the +/− button wraps:

friedbunny · 2016-12-15T20:05:03Z

@mayagao The new screenshot triptych is nice, thanks for updating that. If you have the original sketch/psd/whatever available, please upload that to: platform/ios/originals/screenshots.sketch

If not, please go ahead and delete that file.

mayagao · 2016-12-15T21:02:09Z

Thank you for the detailed feedbacks @1ec5!

make header look better on smaller screens @1ec5
wrap expandable section @1ec5
attaching title attributes @1ec5
capitalize “Github” as “GitHub” @1ec5
make the “View Source on GitHub” link less prominent @1ec5
make small headings in the left navbar look more clickable @friedbunny
upload original sketch @friedbunny

mayagao · 2016-12-15T21:32:44Z

Im going to hold on some of the style changes and avoid making the css too complicated since we are not using base here.

mayagao · 2016-12-16T18:05:57Z

@1ec5 i changed the script to show only macOS docs and iOS docs, it's kind of repetitive to show mapbox twice?

1ec5 · 2016-12-16T18:41:48Z

I agree with removing the redundant “Mapbox” in the header, although it looks like you still need to check in that change to document.sh.

Also, we need to make sure that other instances of “Mapbox iOS SDK Docs/Reference” that don’t appear next to the Mapbox logo still say “Mapbox” in them. Perhaps we can make this easier by using some easily identifiable placeholder instead of {{module_name}} Docs, like BRANDLESS_DOCSET_TITLE.

mayagao · 2016-12-16T18:55:32Z

ok @1ec5 just pushed

1ec5 · 2016-12-16T18:57:27Z

platform/ios/scripts/document.sh

@@ -44,4 +44,4 @@ jazzy \
    --output ${OUTPUT}
 # https://github.com/realm/jazzy/issues/411
 find ${OUTPUT} -name *.html -exec \
-    perl -pi -e 's/Mapbox\s+(Docs|Reference)/Mapbox iOS SDK $1/' {} \;
+    perl -pi -e 's/BRANDLESS_DOCSET_TITLE/iOS SDK $1/' {} \;


We still need the old replacement as well because of places outside the header that end up saying “Mapbox Docs” or “Mapbox References” otherwise.

friedbunny

I bow before @mayagao’s awesome ability.

mayagao · 2016-12-17T00:12:06Z

thank you @1ec5 @friedbunny !

captainbarbosa · 2016-12-20T02:09:32Z

@mayagao This looks great! I'm so glad you took this on. Well done! 🎉

mayagao · 2016-12-20T15:55:06Z

thank you @captainbarbosa 😳😳😳

mayagao force-pushed the add-search branch from 3d42d3a to 5f0d14f Compare December 14, 2016 18:20

friedbunny changed the title ~~[WIP] iOS doc small improvements~~ [WIP] iOS jazzy theme small improvements Dec 14, 2016

friedbunny changed the base branch from master to release-ios-v3.4.0 December 14, 2016 18:56

mayagao added 3 commits December 14, 2016 11:38

some small improvements to the theme

796ddbb

modify theme

b0f2291

link hover color

216ad60

mayagao force-pushed the add-search branch from 7ac427d to 7763877 Compare December 14, 2016 19:40

small table font

1fdadab

mayagao force-pushed the add-search branch from 7763877 to 1fdadab Compare December 14, 2016 22:11

table border-radius

04e4bd2

mayagao force-pushed the add-search branch from 3cd3cad to 04e4bd2 Compare December 14, 2016 23:03

friedbunny assigned mayagao Dec 15, 2016

friedbunny added documentation iOS Mapbox Maps SDK for iOS labels Dec 15, 2016

friedbunny added this to the ios-v3.4.0 milestone Dec 15, 2016

1ec5 suggested changes Dec 15, 2016

View reviewed changes

address feedback, responsive header, anchor icon

7ecab8f

add sketch file

484ac31

use module name

0193f69

mayagao assigned 1ec5 Dec 16, 2016

remove mapbox from the title

80931c2

1ec5 reviewed Dec 16, 2016

View reviewed changes

need the old replacement

676710d

mayagao removed their assignment Dec 16, 2016

friedbunny approved these changes Dec 16, 2016

View reviewed changes

1ec5 approved these changes Dec 16, 2016

View reviewed changes

mayagao merged commit 7f67a29 into release-ios-v3.4.0 Dec 17, 2016

mayagao deleted the add-search branch December 17, 2016 00:11

friedbunny changed the title ~~[WIP] iOS jazzy theme small improvements~~ iOS jazzy theme small improvements Dec 21, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

iOS jazzy theme small improvements #7422

iOS jazzy theme small improvements #7422

mayagao commented Dec 14, 2016 •

edited

Loading

mention-bot commented Dec 14, 2016

friedbunny commented Dec 14, 2016

friedbunny commented Dec 15, 2016

1ec5 left a comment

1ec5 Dec 15, 2016 •

edited

Loading

mayagao Dec 15, 2016

1ec5 Dec 16, 2016 •

edited

Loading

1ec5 Dec 16, 2016

mayagao Dec 16, 2016

1ec5 Dec 15, 2016

friedbunny Dec 15, 2016

1ec5 Dec 15, 2016

friedbunny Dec 15, 2016

1ec5 Dec 15, 2016

1ec5 Dec 15, 2016

1ec5 Dec 15, 2016

1ec5 Dec 15, 2016

1ec5 Dec 15, 2016

1ec5 Dec 15, 2016

1ec5 commented Dec 15, 2016 •

edited

Loading

friedbunny commented Dec 15, 2016 •

edited

Loading

mayagao commented Dec 15, 2016 •

edited

Loading

mayagao commented Dec 15, 2016

mayagao commented Dec 16, 2016

1ec5 commented Dec 16, 2016 •

edited

Loading

mayagao commented Dec 16, 2016

1ec5 Dec 16, 2016

mayagao Dec 16, 2016

friedbunny left a comment

mayagao commented Dec 17, 2016

captainbarbosa commented Dec 20, 2016

mayagao commented Dec 20, 2016

iOS jazzy theme small improvements #7422

iOS jazzy theme small improvements #7422

Conversation

mayagao commented Dec 14, 2016 • edited Loading

Some small problems:

Sketch:

Current status:

mention-bot commented Dec 14, 2016

friedbunny commented Dec 14, 2016

friedbunny commented Dec 15, 2016

1ec5 left a comment

Choose a reason for hiding this comment

1ec5 Dec 15, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1ec5 Dec 16, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1ec5 commented Dec 15, 2016 • edited Loading

friedbunny commented Dec 15, 2016 • edited Loading

mayagao commented Dec 15, 2016 • edited Loading

mayagao commented Dec 15, 2016

mayagao commented Dec 16, 2016

1ec5 commented Dec 16, 2016 • edited Loading

mayagao commented Dec 16, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

friedbunny left a comment

Choose a reason for hiding this comment

mayagao commented Dec 17, 2016

captainbarbosa commented Dec 20, 2016

mayagao commented Dec 20, 2016

mayagao commented Dec 14, 2016 •

edited

Loading

1ec5 Dec 15, 2016 •

edited

Loading

1ec5 Dec 16, 2016 •

edited

Loading

1ec5 commented Dec 15, 2016 •

edited

Loading

friedbunny commented Dec 15, 2016 •

edited

Loading

mayagao commented Dec 15, 2016 •

edited

Loading

1ec5 commented Dec 16, 2016 •

edited

Loading