| -------- |
| Overview |
| |
| This is the content and its server for the extensions/apps documentation served |
| from http://developer.chrome.com/(extensions|apps). |
| |
| Documentation for apps and extensions are partly generated from API definitions |
| (for the reference material), and partly hand-written. |
| |
| All documentation sources are checked into source control, just like any other |
| Chrome source code. The server consumes these sources and generates the |
| documentation web pages dynamically. |
| |
| The goals of this system are: |
| |
| * Docs are generated from API definitions; it isn't possible to add or modify |
| APIs without creating stub reference documentation at the same time. |
| |
| * Docs are editable by anyone with Chrome commit access. This encourages |
| developers to do their part to keep doc up to date, and allows part-time |
| contributors to help too. |
| |
| * Docs go live automatically and immediately, upon check-in. There's no separate |
| push process for docs. |
| |
| * Docs are branched automatically with Chrome's source code; the docs for each |
| Chrome release are kept with the corresponding source code. |
| |
| * Users can always find the current doc for any Chrome release channel (i.e., |
| /trunk/extensions/, /beta/apps/, etc.). These URLs are updated automatically |
| with Chrome's release process. |
| |
| |
| ------------ |
| Editing docs |
| |
| 1. Edit files. |
| |
| - If you are not updating the static HTML for a docs page, you will most |
| likely not have to do anything. The docs server will automatically pick |
| up changes to the JSON or IDL schemas. |
| |
| - Otherwise, they will be in chrome/common/extensions/docs/templates/. |
| See the "Overview of directories" section for more information. |
| Chances are you'll want to change a file in either "intros" (if changing |
| API documentation) or "articles" (if changing non-API documentation). |
| If adding files or APIs you'll also need to add something to "public". |
| |
| - Files in templates directory use the Motemplate template language. It is |
| extremely simple, essentially: write HTML. |
| See third_party/motemplate/README.md. |
| |
| - static/css/out/site.css is generated by compiling static/sass/*.scss |
| files. Don't change site.css directly. Instead, change the *.scss files |
| and run compass from this (docs/) directory: |
| compass compile . |
| See http://compass-style.org/install to install compass. |
| See https://codereview.chromium.org/238303002/#msg6 for configuration |
| information (config.rb). |
| |
| 2. Run 'server2/preview.py' |
| |
| 3. Check your work at http://localhost:8000/(apps|extensions)/<doc_name> |
| |
| 4. Commit files as with any other Chrome change. The live server will update |
| within 5-10 minutes. |
| |
| |
| ----------------------- |
| Overview of directories |
| |
| * examples: The source for the sample extensions. Note that the sample apps are |
| checked into github at https://github.com/GoogleChrome/chrome-app-samples. |
| |
| * server2: The Python AppEngine server which serves all the content (living at |
| developer.chrome.com). Unless you're developing the server itself, you won't |
| need to worry about this (and if you are, see the README in there). |
| |
| * static: The static content (images, CSS, JavaScript, etc). |
| |
| * templates: These are the templates that server2 interprets and generates HTML |
| content with. This has four subdirectories: |
| - intros: The static content that appears before the API reference on API |
| pages. |
| - articles: The static content that appears on non-API pages. |
| - public: The top level templates for all pages. |
| - private: Helper templates used in rendering the docs. |
| |
| |
| -------------------- |
| The AppEngine server |
| |
| See server2/README. |