Cross Reference: /external/chromium/chrome/common/extensions/docs/

This directory contains the chromium extensions documentation, and the mechanism
by which they are generated.

--------------------------------------------------------------------------------
Contributing To The Extension Docs:

[When making changes, open the relevant /<page>.html in chrome via the file:
scheme. If you do, you can refresh to instantly see any changes you make].

*I want to document methods, events or parameters in the api itself:
=>Edit ../api/extension_api.json. Usually you can just add or edit the
"description" property. This will appear automatically in the corresponding doc
page at ./<page>.html (where <page> is the name of the apimodule ("tabs", etc..)
that contains the change you are making.

*I want to edit static content for an API reference module:
=>Look in /static/<page>.html (for your module). If the file exists, edit it,
check you changes by viewing /<page>.html. If the file doesn't exist, add it,
and make a copy of /template/page_shell.html and copy it to /<page>.html.

*I want to edit or add a purely static page:
=>Follow the same steps for editing static content for an API page.

IN ALL CASES. When you have finished, run build/build.bat (on windows) or
build/build.py (on mac/linux). This may generate new files or changes to the
/*.html pages. Include any new or changed files in the changelist you create.

--------------------------------------------------------------------------------
Building

Changes to the extension docs must be checked into source control. Any changes
to any input sources require the docs to be regenerated.

To build the extension docs, run the build.py script in the ./build directory.
This will regenerate the docs and report which, if any, files have changed
and need to be included in the changelist that changed the dependent files.

Note that the build.py script depends on DumpRenderTree to run, so you must be
able to build DumpRenderTree to build extension_docs. The build.py script will
look in typical locations for the DumpRenderTree executable, but you may set
the path to DumpRenderTree explicitly with --dump-render-tree-path.

--------------------------------------------------------------------------------
Design

I. Inputs

There are two sources of input:

1) The contents of ../api/extension_api.json
which contains the "IDL" of the the methods, events, and types of the api. This
file is linked as a resource into the chromium binary and then dynamically
bound to chrome.* objects that are exposed to extension contexts. This file
is fed into the api docs template. It contains both name, type information as
well as documentation contained in "description" properties.

2) The set of ./static/*.html documents. Each of these static html fragments is
inserted into a common template and rendered into ./*.html.

II. Processing

The processing of each document page is as follows:

For each given <page>:
1) A copy of ./page_shell.html is copied to ./<page>.html.
2) This page loads bootstrap.js which inspects the <page> name
3) ./template/api_template.html is loaded and inserted into the body of the page
4) If a ./static/<page>.html exists, its content is inserted into the main
content column of the api_template.html
5) If the <page> matches an api "module" in extension_api.json, the api is then
fed through the api template within api_template.html
6) The result is written on top of the existing /<page>.html. If the new file
differs in content, it is reported as changed by the build.py script.
Name	Date	Size
..	21-Nov-2012	4 KiB
a11y.html	21-Nov-2012	34.1 KiB
api_index.html	21-Nov-2012	20.5 KiB
api_other.html	21-Nov-2012	21.3 KiB
apps.html	21-Nov-2012	23.3 KiB
autoupdate.html	21-Nov-2012	26.8 KiB
background_pages.html	21-Nov-2012	22.3 KiB
bookmarks.html	21-Nov-2012	198.7 KiB
browserAction.html	21-Nov-2012	71.4 KiB
build/	21-Nov-2012	4 KiB
content_scripts.html	21-Nov-2012	37 KiB
contextMenus.html	21-Nov-2012	110 KiB
cookies.html	21-Nov-2012	154.2 KiB
crx.html	21-Nov-2012	23.1 KiB
css/	21-Nov-2012	4 KiB
devguide.html	21-Nov-2012	22.5 KiB
devtools.html	21-Nov-2012	15.4 KiB
docs.html	21-Nov-2012	22.2 KiB
events.html	21-Nov-2012	19.6 KiB
examples/	21-Nov-2012	4 KiB
experimental.clipboard.html	21-Nov-2012	37.3 KiB
experimental.contentSettings.misc.html	21-Nov-2012	26 KiB
experimental.contextMenus.html	21-Nov-2012	18.6 KiB
experimental.cookies.html	21-Nov-2012	18.6 KiB
experimental.debugger.html	21-Nov-2012	54 KiB
experimental.extension.html	21-Nov-2012	68.2 KiB
experimental.history.html	21-Nov-2012	18.6 KiB
experimental.html	21-Nov-2012	22 KiB
experimental.idle.html	21-Nov-2012	18.6 KiB
experimental.infobars.html	21-Nov-2012	30.5 KiB
experimental.processes.html	21-Nov-2012	42.7 KiB
experimental.proxy.html	21-Nov-2012	78.4 KiB
experimental.sidebar.html	21-Nov-2012	99 KiB
experimental.tts.html	21-Nov-2012	78.5 KiB
experimental.webInspector.audits.html	21-Nov-2012	112 KiB
experimental.webInspector.html	21-Nov-2012	21.2 KiB
experimental.webInspector.inspectedWindow.html	21-Nov-2012	29.6 KiB
experimental.webInspector.panels.html	21-Nov-2012	105.7 KiB
experimental.webInspector.resources.html	21-Nov-2012	38 KiB
experimental.webNavigation.html	21-Nov-2012	97.9 KiB
experimental.webRequest.html	21-Nov-2012	125.1 KiB
extension.html	21-Nov-2012	148.4 KiB
external_extensions.html	21-Nov-2012	27.3 KiB
faq.html	21-Nov-2012	39.9 KiB
getstarted.html	21-Nov-2012	24.1 KiB
history.html	21-Nov-2012	117.5 KiB
hosting.html	21-Nov-2012	21 KiB
i18n-messages.html	21-Nov-2012	26.6 KiB
i18n.html	21-Nov-2012	50.1 KiB
idle.html	21-Nov-2012	27.5 KiB
images/	21-Nov-2012	4 KiB
index.html	21-Nov-2012	21.4 KiB
js/	21-Nov-2012	4 KiB
management.html	21-Nov-2012	105.2 KiB
manifest.html	21-Nov-2012	34.7 KiB
match_patterns.html	21-Nov-2012	23.7 KiB
messaging.html	21-Nov-2012	29.6 KiB
notifications.html	21-Nov-2012	22.4 KiB
npapi.html	21-Nov-2012	21.7 KiB
omnibox.html	21-Nov-2012	46.4 KiB
options.html	21-Nov-2012	21.2 KiB
override.html	21-Nov-2012	23 KiB
overview.html	21-Nov-2012	39.3 KiB
packaging.html	21-Nov-2012	23.1 KiB
pageAction.html	21-Nov-2012	61.9 KiB
permission_warnings.html	21-Nov-2012	28.1 KiB
README.txt	21-Nov-2012	3.4 KiB
samples.html	21-Nov-2012	180.7 KiB
samples.json	21-Nov-2012	71.5 KiB
server/	21-Nov-2012	4 KiB
static/	21-Nov-2012	4 KiB
tabs.html	21-Nov-2012	277.8 KiB
template/	21-Nov-2012	4 KiB
test.html	21-Nov-2012	25.4 KiB
themes.html	21-Nov-2012	23.6 KiB
tut_analytics.html	21-Nov-2012	25.9 KiB
tut_debugging.html	21-Nov-2012	26 KiB
tut_oauth.html	21-Nov-2012	28.4 KiB
tutorials.html	21-Nov-2012	19 KiB
whats_new.html	21-Nov-2012	25.5 KiB
windows.html	21-Nov-2012	142.1 KiB
xhr.html	21-Nov-2012	23.4 KiB