Basic setup for generating app docs

Basic setup for generating apps docs.

It turns out that we don't need to tag anything. Putting the page shell inside extensions/ or apps/ works better with the current state of the code.

In order to do the transition, I propose:

1) Land and push a change to the appengine server to make it look in /docs/extensions, then fall back to /docs.

2) Land this CL (without any apps files fleshed out)

3) Add support to app engine server to know about the apps folder too (can test by going to its app engine URL)

4) Flesh out the apps docs

5) Apply the new template

6) Fix the one-off things like generation of experimental.html that need to be fixed for apps-specific.

[3-6 can be done in parallel]

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

[Aaron Boodman, 2012-06-22 11:26:21]

Ernest, this is based on your approach, but I changed some things. It turns out
we don't need to tag files individually because just having a page shell in the
dest directory can serve that same purpose. And the code works with less changes
this way.

[Yoyo Zhou, 2012-06-22 19:05:55]

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/apps/bookmarks.html (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/apps/bookmarks.html:56: <td valign="middle"><a
href="http://code.google.com/"><img src="images/chrome_logo.gif" alt="Google
Code" style="border:0; margin:0;"></a></td>
Why are there changes like this? Have people just been negligent in generating
their docs?

Also, this seems to be the only file in docs/apps/ -- any reason for that?

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/build/build.py (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/build/build.py:61: return []
Silently fail? The old code threw an exception.

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/build/build.py:70: input_file =
os.path.join(output_dir, name + ".html")
input_file looks like the wrong name for this. More like output_file.

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/js/api_page_generator.js (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/js/api_page_generator.js:160: // TODO(aa): Ugh,
this is horrible. FIXME.
Not sure of the best thing to do here, but one alternative is a regex with a
capturing group. Something like

^/chrome-or-whatever/(extensions|apps)/

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/js/api_page_generator.js:166: var apiTemplate =
docFamily == "extensions" ?
I wonder if there should be an error if it's neither "extensions" nor "apps".

[Aaron Boodman, 2012-06-22 22:16:47]

ptal

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/apps/bookmarks.html (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/apps/bookmarks.html:56: <td valign="middle"><a
href="http://code.google.com/"><img src="images/chrome_logo.gif" alt="Google
Code" style="border:0; margin:0;"></a></td>
On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> Why are there changes like this? Have people just been negligent in generating
> their docs?

This file is actually new. Note the path is apps/bookmarks.html, not
extensions/bookmarks.html.

I was using this file as a test case of the new behavior. We won't actually have
an apps/bookmarks.html, but any file that we put in apps/ should get the apps
template, not the extensions template.

You're seeing the differences between the two templates on the generated output
here.

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/build/build.py (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/build/build.py:61: return []
On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> Silently fail? The old code threw an exception.

We now run this function twice: once with extensions and once with apps. It can
be possible that the single page specified is not in one of those sets
legitimately.

I don't think the exception was that useful.

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/build/build.py:70: input_file =
os.path.join(output_dir, name + ".html")
On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> input_file looks like the wrong name for this. More like output_file.

Done.

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/js/api_page_generator.js (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/js/api_page_generator.js:160: // TODO(aa): Ugh,
this is horrible. FIXME.
On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> Not sure of the best thing to do here, but one alternative is a regex with a
> capturing group. Something like
> 
> ^/chrome-or-whatever/(extensions|apps)/

Won't work. Added additional commentary.

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/js/api_page_generator.js:166: var apiTemplate =
docFamily == "extensions" ?
On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> I wonder if there should be an error if it's neither "extensions" nor "apps".

Done.

[Yoyo Zhou, 2012-06-22 22:26:06]

LGTM, with more regular expression suggestions

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/build/build.py (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/build/build.py:61: return []
On 2012/06/22 22:16:48, Aaron Boodman wrote:
> On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> > Silently fail? The old code threw an exception.
> 
> We now run this function twice: once with extensions and once with apps. It
can
> be possible that the single page specified is not in one of those sets
> legitimately.
> 
> I don't think the exception was that useful.

I guess the user would be told that there were no changes.

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/js/api_page_generator.js (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/js/api_page_generator.js:160: // TODO(aa): Ugh,
this is horrible. FIXME.
On 2012/06/22 22:16:48, Aaron Boodman wrote:
> On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> > Not sure of the best thing to do here, but one alternative is a regex with a
> > capturing group. Something like
> > 
> > ^/chrome-or-whatever/(extensions|apps)/
> 
> Won't work. Added additional commentary.

Oh, I misread the length - 2 as 2 for some reason. Then it seems like something
like the following would work:

(extensions|apps)/[^/]+\.html$

[Aaron Boodman, 2012-06-22 22:34:14]

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
File chrome/common/extensions/docs/js/api_page_generator.js (right):

https://chromiumcodereview.appspot.com/10642015/diff/5030/chrome/common/exten...
chrome/common/extensions/docs/js/api_page_generator.js:160: // TODO(aa): Ugh,
this is horrible. FIXME.
On 2012/06/22 22:26:06, Yoyo Zhou wrote:
> On 2012/06/22 22:16:48, Aaron Boodman wrote:
> > On 2012/06/22 19:05:55, Yoyo Zhou wrote:
> > > Not sure of the best thing to do here, but one alternative is a regex with
a
> > > capturing group. Something like
> > > 
> > > ^/chrome-or-whatever/(extensions|apps)/
> > 
> > Won't work. Added additional commentary.
> 
> Oh, I misread the length - 2 as 2 for some reason. Then it seems like
something
> like the following would work:
> 
> (extensions|apps)/[^/]+\.html$

It's not the hard-code number that bothers me, but the assumption that HTML
files are only in the root directory. Regexes just seem like a more obtuse way
to say the same thing.