Rework API reference pages

Rework API reference pages
(this is a fresh copy of https://codereview.chromium.org/121713002/ with correct BaseURL)

BUG=340702
NOTRY=true

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=251240

[Renato Mangini (chromium), 2014-02-06 03:20:37]

PTAL

I've addressed all comments from Kalman on the original CL
(https://codereview.chromium.org/121713002/)

[Jeffrey Yasskin, 2014-02-07 02:40:03]

I also noticed that the deprecation warning looks bad inside the new tables:
http://localhost:8000/extensions/tabs.html#Tab-properties

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
File chrome/common/extensions/docs/static/sass/_api.scss (right):

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:2: color: #333;
Contrast ratio 12.6:1.

I wonder if we should comment these in the CSS so that we remember to strictly
avoid falling below the WCAG rules, and to try to avoid low-contrast text in
places we want people to read. I'm computing contrasts with
http://webaim.org/resources/contrastchecker/.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:5: .api-summary {
This hasn't been propagated to the compiled css, which means my attempt to look
at the UI didn't give me the expected results.

I understand this is going to be more automatic in the future.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:13: td:hover a, td:hover a *
{
We shouldn't have a UI that requires you to scan your mouse over the page in
order to find what's interactive. Besides being annoying, it doesn't work at all
on mobile.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:16: font-weight: bold;
We shouldn't change the size of text on hover. It causes unpleasant jumping
effects.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:31: background: none;
Please comment which background this cancels.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:34: margin: 0;
Do we have any places where we have 2 paragraphs in an innerTable? If so, this
is going to remove all the space between them, which seems less than ideal. You
could get it back with "p+p{margin-top:whatever}".

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:41: background: #fafafa;
Contrast ratio 12.1:1

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:44: background-color:
darken($gray-light, 5%);
Contrast ratio 17.1:1

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:50: margin-top: rhythm(2);
Is there a good way to search for the definitions of functions like this? I had
to click through most of the compass site before I found
http://compass-style.org/reference/compass/typography/vertical_rhythm/#functi...,
and even that doesn't explain what a "rhythm" or rhythm unit is. If I'm not just
missing an obvious reference, please comment this.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
File chrome/common/extensions/docs/templates/private/api.html (left):

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/templates/private/api.html:17: {{?api.deprecated
+partials.warning_deprecated item:api/}}
Does this need to exist somewhere else?

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
File chrome/common/extensions/docs/templates/private/api.html (right):

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/templates/private/api.html:17: <div
itemprop="articleBody" class="api">
This is an odd use of itemprop:
http://developers.whatwg.org/microdata.html#names:-the-itemprop-attribute.
There's no itemscope to create the item it's a property on. What's it for? 

Do you need the separate <article> and <div> layers at all? Can they just be a
single element?

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
File chrome/common/extensions/docs/templates/private/api_property.html (right):

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/templates/private/api_property.html:11: <table
class="innerTable">
Nested tables don't look great, although I'm reasonably happy to let this
through and iterate.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
File chrome/common/extensions/docs/templates/private/api_summary.html (right):

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/templates/private/api_summary.html:6: <tr><th
colspan="2">Types</th></tr>
This table only has one column.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/templates/private/api_summary.html:14: <tr><td><a
href="#{{p.id}}">{{p.name}}</a></td>
Why do we list just the basename of the properties and events, but spell out
chrome.namespace.function?

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/templates/private/api_summary.html:14: <tr><td><a
href="#{{p.id}}">{{p.name}}</a></td>
This row is missing its </tr>. It's not required by HTML, but we should be
consistent.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
File chrome/common/extensions/docs/templates/private/type.html (right):

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/templates/private/type.html:16: <dd>
What's this <dd> doing in the middle of a <table>?

[not at google - send to devlin, 2014-02-13 23:35:35]

Thanks Renato and Jeffrey for putting so much time into this, it's a huge
improvement.

Since Jeffrey is away and we're trying to iterate quickly here, let's submit
this now and do a follow up ASAP. The content right now is not launchable; this
is.

lgtm

[Renato Mangini (chromium), 2014-02-14 00:50:50]

addressed some comments from reviewers. Smuggled a totally unrelated change in
this CL: a different chrome logo, as requested by the marketing team.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
File chrome/common/extensions/docs/static/sass/_api.scss (right):

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:2: color: #333;
Good point. As you noticed, at least for API pages I've made text darker while
we wait designers clearance to also apply it to the rest.

Checking contrast ratio and WCAG rules is a good tip, but I think it should be
done by designers, not in CSS. The additional comments would make the CSS harder
to maintain, since it would need to be changed whenever the background color
changes - and would only make sense if the text is used in a single background.

On 2014/02/07 02:40:03, Jeffrey Yasskin wrote:
> Contrast ratio 12.6:1.
> 
> I wonder if we should comment these in the CSS so that we remember to strictly
> avoid falling below the WCAG rules, and to try to avoid low-contrast text in
> places we want people to read. I'm computing contrasts with
> http://webaim.org/resources/contrastchecker/.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:5: .api-summary {

You need to compile SASS files. And yes, it will be more automatic when SASS
native support is added (AFAIK CL in progress by hukun)

On 2014/02/07 02:40:03, Jeffrey Yasskin wrote:
> This hasn't been propagated to the compiled css, which means my attempt to
look
> at the UI didn't give me the expected results.
> 
> I understand this is going to be more automatic in the future.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:13: td:hover a, td:hover a *
{
On 2014/02/07 02:40:03, Jeffrey Yasskin wrote:
> We shouldn't have a UI that requires you to scan your mouse over the page in
> order to find what's interactive. Besides being annoying, it doesn't work at
all
> on mobile.

Done. Added a link with the function name and the syntax highlighted signature
with no link.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:16: font-weight: bold;
On 2014/02/07 02:40:03, Jeffrey Yasskin wrote:
> We shouldn't change the size of text on hover. It causes unpleasant jumping
> effects.

Done.

https://codereview.chromium.org/149673004/diff/110001/chrome/common/extension...
chrome/common/extensions/docs/static/sass/_api.scss:50: margin-top: rhythm(2);
On 2014/02/07 02:40:03, Jeffrey Yasskin wrote:
> Is there a good way to search for the definitions of functions like this? I
had
> to click through most of the compass site before I found
>
http://compass-style.org/reference/compass/typography/vertical_rhythm/#functi...,
> and even that doesn't explain what a "rhythm" or rhythm unit is. If I'm not
just
> missing an obvious reference, please comment this.

Done.

[Renato Mangini (chromium), 2014-02-14 00:51:11]

The CQ bit was checked by mangini@chromium.org

[commit-bot: I haz the power, 2014-02-14 00:51:45]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/mangini@chromium.org/149673004/420001

[commit-bot: I haz the power, 2014-02-14 02:57:51]

The CQ bit was unchecked by commit-bot@chromium.org

[commit-bot: I haz the power, 2014-02-14 02:57:52]

Retried try job too often on win_rel for step(s) check_deps
http://build.chromium.org/p/tryserver.chromium/buildstatus?builder=win_rel&nu...

[Renato Mangini (chromium), 2014-02-14 03:04:32]

The CQ bit was checked by mangini@chromium.org

[commit-bot: I haz the power, 2014-02-14 03:07:42]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/mangini@chromium.org/149673004/420001

[commit-bot: I haz the power, 2014-02-14 03:07:50]

The CQ bit was unchecked by commit-bot@chromium.org

[commit-bot: I haz the power, 2014-02-14 03:07:52]

Failed to apply patch for chrome/common/extensions/docs/server2/app.yaml:
While running patch -p1 --forward --force --no-backup-if-mismatch;
  patching file chrome/common/extensions/docs/server2/app.yaml
  Hunk #1 FAILED at 1.
  1 out of 1 hunk FAILED -- saving rejects to file
chrome/common/extensions/docs/server2/app.yaml.rej

Patch:       chrome/common/extensions/docs/server2/app.yaml
Index: chrome/common/extensions/docs/server2/app.yaml
diff --git a/chrome/common/extensions/docs/server2/app.yaml
b/chrome/common/extensions/docs/server2/app.yaml
index
fcfe0bd4a63e67e75c14fffcc904f1b94dcd2d90..bbcafabaf3811aa66fe7019e59b694c067abeb11
100644
--- a/chrome/common/extensions/docs/server2/app.yaml
+++ b/chrome/common/extensions/docs/server2/app.yaml
@@ -1,5 +1,5 @@
 application: chrome-apps-doc
-version: 3-9-0
+version: 3-9-1
 runtime: python27
 api_version: 1
 threadsafe: false

[Renato Mangini (chromium), 2014-02-14 03:12:12]

The CQ bit was checked by mangini@chromium.org

[commit-bot: I haz the power, 2014-02-14 03:13:11]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/mangini@chromium.org/149673004/850001

[commit-bot: I haz the power, 2014-02-14 03:17:36]

Change committed as 251240