README.txt
1 This directory contains the chromium extensions documentation, and the mechanism 2 by which they are generated. 3 4 -------------------------------------------------------------------------------- 5 Contributing To The Extension Docs: 6 7 [When making changes, open the relevant /<page>.html in chrome via the file: 8 scheme. 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 13 page at ./<page>.html (where <page> is the name of the apimodule ("tabs", etc..) 14 that 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, 18 check you changes by viewing /<page>.html. If the file doesn't exist, add it, 19 and 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 24 IN ALL CASES. When you have finished, run build/build.bat (on windows) or 25 build/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 -------------------------------------------------------------------------------- 29 Building 30 31 Changes to the extension docs must be checked into source control. Any changes 32 to any input sources require the docs to be regenerated. 33 34 To build the extension docs, run the build.py script in the ./build directory. 35 This will regenerate the docs and report which, if any, files have changed 36 and need to be included in the changelist that changed the dependent files. 37 38 Note that the build.py script depends on DumpRenderTree to run, so you must be 39 able to build DumpRenderTree to build extension_docs. The build.py script will 40 look in typical locations for the DumpRenderTree executable, but you may set 41 the path to DumpRenderTree explicitly with --dump-render-tree-path. 42 43 -------------------------------------------------------------------------------- 44 Design 45 46 I. Inputs 47 48 There are two sources of input: 49 50 1) The contents of ../api/extension_api.json 51 which contains the "IDL" of the the methods, events, and types of the api. This 52 file is linked as a resource into the chromium binary and then dynamically 53 bound to chrome.* objects that are exposed to extension contexts. This file 54 is fed into the api docs template. It contains both name, type information as 55 well as documentation contained in "description" properties. 56 57 2) The set of ./static/*.html documents. Each of these static html fragments is 58 inserted into a common template and rendered into ./*.html. 59 60 II. Processing 61 62 The processing of each document page is as follows: 63 64 For each given <page>: 65 1) A copy of ./page_shell.html is copied to ./<page>.html. 66 2) This page loads bootstrap.js which inspects the <page> name 67 3) ./template/api_template.html is loaded and inserted into the body of the page 68 4) If a ./static/<page>.html exists, its content is inserted into the main 69 content column of the api_template.html 70 5) If the <page> matches an api "module" in extension_api.json, the api is then 71 fed through the api template within api_template.html 72 6) The result is written on top of the existing /<page>.html. If the new file 73 differs in content, it is reported as changed by the build.py script. 74
