Extensions Docs Server: devtools API

Extensions Docs Server: fix rendering of the Devtools API.

This change splits devtools_api.json into a separate file per namespace so that
JSON schema compiler can parse it. Without that, HandlebarDictGenerator can't
access the API, and the docs server can't render it

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

[cduvall, 2012-07-19 22:54:16]

Devtools API. Yay!

https://chromiumcodereview.appspot.com/10797039/diff/2001/chrome/common/exten...
File chrome/common/extensions/api/devtools/network.json (right):

https://chromiumcodereview.appspot.com/10797039/diff/2001/chrome/common/exten...
chrome/common/extensions/api/devtools/network.json:55: "type": "any",
FYI, I changed this and a few others from "object" to "any" because the schema
compiler didn't like the objects not having properties/functions/types.

[not at google - send to devlin, 2012-07-20 00:26:35]

+caseq for devtools.

Clark, you might want to give a bit more background in the description about why
we're splitting up the JSON...

https://chromiumcodereview.appspot.com/10797039/diff/2001/chrome/common/exten...
File chrome/common/extensions/api/devtools/network.json (right):

https://chromiumcodereview.appspot.com/10797039/diff/2001/chrome/common/exten...
chrome/common/extensions/api/devtools/network.json:55: "type": "any",
On 2012/07/19 22:54:16, cduvall wrote:
> FYI, I changed this and a few others from "object" to "any" because the schema
> compiler didn't like the objects not having properties/functions/types.

I'm not sure this is right though. Looking at HAR, it *is* an object. What
doesn't JSC like about it being object?

[cduvall, 2012-07-20 00:31:09]

Added better description.

https://chromiumcodereview.appspot.com/10797039/diff/2001/chrome/common/exten...
File chrome/common/extensions/api/devtools/network.json (right):

https://chromiumcodereview.appspot.com/10797039/diff/2001/chrome/common/exten...
chrome/common/extensions/api/devtools/network.json:55: "type": "any",
On 2012/07/20 00:26:35, kalman wrote:
> On 2012/07/19 22:54:16, cduvall wrote:
> > FYI, I changed this and a few others from "object" to "any" because the
schema
> > compiler didn't like the objects not having properties/functions/types.
> 
> I'm not sure this is right though. Looking at HAR, it *is* an object. What
> doesn't JSC like about it being object?

It throws the exception here:
http://code.google.com/searchframe#OAMlx_jo-ck/src/tools/json_schema_compiler...

[not at google - send to devlin, 2012-07-20 00:33:59]

I think you'll want to add "additionalProperties": {type: "any"} then.

[cduvall, 2012-07-20 00:38:44]

On 2012/07/20 00:33:59, kalman wrote:
> I think you'll want to add "additionalProperties": {type: "any"} then.

Fixed.

[cduvall, 2012-07-25 01:10:57]

+pfeldman for devtools API

[caseq, 2012-07-25 13:36:06]

So you're adding {inspected_window,network,panels}.json but not removing these
APIs from devtools_api.json -- is this intentional?

[cduvall, 2012-07-25 15:46:51]

On 2012/07/25 13:36:06, caseq wrote:
> So you're adding {inspected_window,network,panels}.json but not removing these
> APIs from devtools_api.json -- is this intentional?

Yes, this is intentional. The old documentation still uses the devtools_api.json
file, so it will be left there until we start using the new documentation
server.

[caseq, 2012-07-25 16:37:32]

On 2012/07/25 15:46:51, cduvall wrote:
> On 2012/07/25 13:36:06, caseq wrote:
> > So you're adding {inspected_window,network,panels}.json but not removing
these
> > APIs from devtools_api.json -- is this intentional?
> 
> Yes, this is intentional. The old documentation still uses the
devtools_api.json
> file, so it will be left there until we start using the new documentation
> server.

That would be quite unfortunate -- we would have to maintain two copies then.
How hard would it be to fix the old doc build scripts as well?

[cduvall, 2012-07-25 17:57:25]

On 2012/07/25 16:37:32, caseq wrote:
> On 2012/07/25 15:46:51, cduvall wrote:
> > On 2012/07/25 13:36:06, caseq wrote:
> > > So you're adding {inspected_window,network,panels}.json but not removing
> these
> > > APIs from devtools_api.json -- is this intentional?
> > 
> > Yes, this is intentional. The old documentation still uses the
> devtools_api.json
> > file, so it will be left there until we start using the new documentation
> > server.
> 
> That would be quite unfortunate -- we would have to maintain two copies then.
> How hard would it be to fix the old doc build scripts as well?

Ok, the old devtools_api.json file is gone, and now the old docs use the files
in devtools/ .

[caseq, 2012-07-25 18:05:36]

> Ok, the old devtools_api.json file is gone, and now the old docs use the files
> in devtools/ .

I'm afraid we've lost a few experimental APIs this way (audits, console,
timeline)

[cduvall, 2012-07-25 18:07:19]

On 2012/07/25 18:05:36, caseq wrote:
> > Ok, the old devtools_api.json file is gone, and now the old docs use the
files
> > in devtools/ .
> 
> I'm afraid we've lost a few experimental APIs this way (audits, console,
> timeline)

Ahh curse you old documentation. I'll see what I can do.

[cduvall, 2012-07-25 20:46:17]

caseq: console and audits are back in but I couldn't find anything on timeline.
Is there a page for experimental.devtools.timeline in the old docs? Where is
this API defined?

Thanks for the review!

[caseq, 2012-07-27 17:51:51]

On 2012/07/25 20:46:17, cduvall wrote:
> caseq: console and audits are back in but I couldn't find anything on
timeline.

LGTM wrt schema split and old docs build scripts (can't say much about server2/
stuff). Thanks for fixing it!

> Is there a page for experimental.devtools.timeline in the old docs? > Where is
this API defined?

Oops. My bad -- we actually have not yet documented it :)

[not at google - send to devlin, 2012-07-30 08:17:20]

I think this might need to be synced to tip, like, the events stuff in model.py
should be exposed soon.

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
File chrome/common/extensions/docs/server2/api_list_data_source.py (right):

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
chrome/common/extensions/docs/server2/api_list_data_source.py:23: return
filename
This will have to play well with things like
- links within the API (like $ref:experimental.devtools.foo)
- API lists
- basically any time that a link to an API needs to be generated.

and I note that similar logic is repeated in a few places.

so you might want to pull this logic into a separate module.

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
File
chrome/common/extensions/docs/server2/templates/articles/experimental_devtools.html
(right):

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
chrome/common/extensions/docs/server2/templates/articles/experimental_devtools.html:5:
href="devtools.html">chrome.devtools.* APIs</a> for the guidelines on how to use
looks like we'll need a devtools.html

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
File
chrome/common/extensions/docs/server2/templates/intros/experimental_devtools_console.html
(right):

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
chrome/common/extensions/docs/server2/templates/intros/experimental_devtools_console.html:11:
<!-- END AUTHORED CONTENT -->
delete this <!-- AUTHORED CONTENT --> stuff

Same goes for all the other docs that add them.

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
File
chrome/common/extensions/docs/server2/templates/private/standard_article.html
(right):

https://chromiumcodereview.appspot.com/10797039/diff/21003/chrome/common/exte...
chrome/common/extensions/docs/server2/templates/private/standard_article.html:13:
{{?article.toc}}{{+partials.table_of_contents toc:article.toc}}{{/}}
you might want to make this

{{?article.toc}}
{{+partials..}}
{{/article.toc}}

so that it gets rendered as a block rather than inline.

[cduvall, 2012-07-31 18:41:45]

Addressed comments. I'd like to get this in before the docs conversion script,
so that we can make sure the conversion script handles this.

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
File chrome/common/extensions/docs/server2/api_list_data_source.py (right):

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
chrome/common/extensions/docs/server2/api_list_data_source.py:23: return
filename
On 2012/07/30 08:17:20, kalman wrote:
> This will have to play well with things like
> - links within the API (like $ref:experimental.devtools.foo)
> - API lists
> - basically any time that a link to an API needs to be generated.
> 
> and I note that similar logic is repeated in a few places.
> 
> so you might want to pull this logic into a separate module.

This is not used for handling $refs, this is just for handling filenames (like
devtools/panels.json). It handles things like devtools/experimental_panels.json
correctly.

Once this change and the conversion script are in, I'm going to make sure all
the $refs are handled right.

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
File
chrome/common/extensions/docs/server2/templates/articles/experimental_devtools.html
(right):

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
chrome/common/extensions/docs/server2/templates/articles/experimental_devtools.html:5:
href="devtools.html">chrome.devtools.* APIs</a> for the guidelines on how to use
On 2012/07/30 08:17:20, kalman wrote:
> looks like we'll need a devtools.html

Already have one :)

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
File
chrome/common/extensions/docs/server2/templates/intros/experimental_devtools_console.html
(right):

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
chrome/common/extensions/docs/server2/templates/intros/experimental_devtools_console.html:11:
<!-- END AUTHORED CONTENT -->
On 2012/07/30 08:17:20, kalman wrote:
> delete this <!-- AUTHORED CONTENT --> stuff
> 
> Same goes for all the other docs that add them.

The docs conversion script will remove all of these. I'm going to wait to remove
them until that goes in.

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
File
chrome/common/extensions/docs/server2/templates/private/standard_article.html
(right):

http://codereview.chromium.org/10797039/diff/21003/chrome/common/extensions/d...
chrome/common/extensions/docs/server2/templates/private/standard_article.html:13:
{{?article.toc}}{{+partials.table_of_contents toc:article.toc}}{{/}}
On 2012/07/30 08:17:20, kalman wrote:
> you might want to make this
> 
> {{?article.toc}}
> {{+partials..}}
> {{/article.toc}}
> 
> so that it gets rendered as a block rather than inline.

Done.

[not at google - send to devlin, 2012-07-31 21:58:05]

lgtm