Docserver: Fix the TOC rendering for API references by fixing the haphazard way

Docserver: Fix the TOC rendering for API references by fixing the haphazard way
that header tags are used in the API reference (legacy reasons) and adding some
features to the TOC document parsing to support a cleaner TOC.

BUG=325555
R=mkearney@chromium.org, yoz@chromium.org

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

[not at google - send to devlin, 2013-12-10 19:31:14]

Yoyo for the server stuff (and the content if you'd like), Meggin for the
content.

To test:
- the current live server isn't rendering any reference TOC at all.
- the newest version is very obviously broken, and you can see this by browsing
e.g. http://2-44-1.chrome-apps-doc.appspot.com/extensions/storage.html
- patch in this and explore to see what it looks like.

The content does change a bit too, so make sure you're ok with that.

[Yoyo Zhou, 2013-12-10 23:48:22]

LGTM
Does this fix https://code.google.com/p/chromium/issues/detail?id=323713 also
now?

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/server2/document_parser.py (right):

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/server2/document_parser.py:135: # The document can
specify title="" to ignore the TOC entry entirely.
The wording is a little confusing - how about something like:
Don't create a TOC entry at all if the tag has specified title=""

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/server2/known_broken_links.json (right):

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/server2/known_broken_links.json:2020:
"extensions/tabs.html",
? This is a duplicate entry?

[mkearney1, 2013-12-11 02:00:27]

Tonight, I just did a visual test off of patch preview.

So I'm putting review comments here:

** Can we use h1 for page title and reference title, but not the sections
beneath that? Currently sections beneath the page title and the auto-generated
sections beneath the reference title are the same size. They should be smaller.

** More specifically, can Manifest, Example, Types, etc. be h2?

Tomorrow, I'll bring the new site design together with this patch to see how it
all comes together. And I'll add more comments.

[mkearney1, 2013-12-11 22:20:09]

lgtm... with reminder to make sure Eric B knows about site.css changes.

[not at google - send to devlin, 2013-12-11 22:23:22]

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/server2/document_parser.py (right):

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/server2/document_parser.py:135: # The document can
specify title="" to ignore the TOC entry entirely.
On 2013/12/10 23:48:23, Yoyo Zhou wrote:
> The wording is a little confusing - how about something like:
> Don't create a TOC entry at all if the tag has specified title=""

Done.

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/server2/known_broken_links.json (right):

https://codereview.chromium.org/99703004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/server2/known_broken_links.json:2020:
"extensions/tabs.html",
On 2013/12/10 23:48:23, Yoyo Zhou wrote:
> ? This is a duplicate entry?

Huh weird. It's all done automatically. I'll look into it, maybe the integration
tests need to set(..)-ify something.

[not at google - send to devlin, 2013-12-12 00:16:51]

Committed patchset #3 manually as r240228 (presubmit successful).