README.txt revision 8ae428e0fb7feea16d79853f29447469a93bedff 
1This directory contains the chromium extensions documentation, and the mechanism
2by which they are generated.
3
4--------------------------------------------------------------------------------
5Contributing To The Extension Docs:
6
7[When making changes, open the relevant /<page>.html in chrome via the file:
8scheme. If you do, you can refresh to instantly see any changes you make].
9
10*I want to document methods, events or parameters in the api itself:
11=>Edit ../api/extension_api.json. Usually you can just add or edit the
12"description" property. This will appear automatically in the corresponding doc
13page at ./<page>.html (where <page> is the name of the apimodule ("tabs", etc..)
14that contains the change you are making.
15
16*I want to edit static content for an API reference module:
17=>Look in /static/<page>.html (for your module). If the file exists, edit it,
18check you changes by viewing /<page>.html. If the file doesn't exist, add it,
19and make a copy of /template/page_shell.html and copy it to /<page>.html.
20
21*I want to edit or add a purely static page:
22=>Follow the same steps for editing static content for an API page.
23
24IN ALL CASES. When you have finished, run build/build.bat (on windows) or
25build/build.py (on mac/linux). This may generate new files or changes to the
26/*.html pages. Include any new or changed files in the changelist you create.
27
28--------------------------------------------------------------------------------
29Building
30
31Changes to the extension docs must be checked into source control. Any changes
32to any input sources require the docs to be regenerated.
33
34To build the extension docs, run the build.py script in the ./build directory.
35This will regenerate the docs and report which, if any, files have changed
36and need to be included in the changelist that changed the dependent files.
37
38Note that the build.py script depends on test_shell to run, so you must be
39able to build test_shell to build extension_docs. The build.py script will
40look in typical locations for the test_shell executable, but you may set
41the path to test_shell explicitly with --test-shell-path.
42
43--------------------------------------------------------------------------------
44Design
45
46I. Inputs
47
48There are two sources of input:
49
501) The contents of ../api/extension_api.json
51which contains the "IDL" of the the methods, events, and types of the api. This
52file is linked as a resource into the chromium binary and then dynamically
53bound to chrome.* objects that are exposed to extension contexts. This file
54is fed into the api docs template. It contains both name, type information as
55well as documentation contained in "description" properties.
56
572) The set of ./static/*.html documents. Each of these static html fragments is
58inserted into a common template and rendered into ./*.html.
59
60II. Processing
61
62The processing of each document page is as follows:
63
64For each given <page>:
651) A copy of ./page_shell.html is copied to ./<page>.html.
662) This page loads bootstrap.js which inspects the <page> name
673) ./template/api_template.html is loaded and inserted into the body of the page
684) If a ./static/<page>.html exists, its content is inserted into the main
69content column of the api_template.html
705) If the <page> matches an api "module" in extension_api.json, the api is then
71fed through the api template within api_template.html
726) The result is written on top of the existing /<page>.html. If the new file
73differs in content, it is reported as changed by the build.py script.
74