Home | History | Annotate | only in /external/chromium_org/chrome/common/extensions/docs
Up to higher level directory
NameDateSize
.gitignore16-Dec-201412
examples/16-Dec-2014
OWNERS10-Mar-2015240
README10-Mar-20153.8K
server2/10-Mar-2015
static/16-Dec-2014
templates/16-Dec-2014

README

      1 --------
      2 Overview
      3 
      4 This is the content and its server for the extensions/apps documentation served
      5 from http://developer.chrome.com/(extensions|apps).
      6 
      7 Documentation for apps and extensions are partly generated from API definitions
      8 (for the reference material), and partly hand-written.
      9 
     10 All documentation sources are checked into source control, just like any other
     11 Chrome source code. The server consumes these sources and generates the
     12 documentation web pages dynamically.
     13 
     14 The goals of this system are:
     15 
     16 * Docs are generated from API definitions; it isn't possible to add or modify
     17   APIs without creating stub reference documentation at the same time.
     18 
     19 * Docs are editable by anyone with Chrome commit access. This encourages
     20   developers to do their part to keep doc up to date, and allows part-time
     21   contributors to help too.
     22 
     23 * Docs go live automatically and immediately, upon check-in. There's no separate
     24   push process for docs.
     25 
     26 * Docs are branched automatically with Chrome's source code; the docs for each
     27   Chrome release are kept with the corresponding source code.
     28 
     29 * Users can always find the current doc for any Chrome release channel (i.e.,
     30   /trunk/extensions/, /beta/apps/, etc.). These URLs are updated automatically
     31   with Chrome's release process.
     32 
     33 
     34 ------------
     35 Editing docs
     36 
     37   1. Edit files.
     38 
     39      - If you are not updating the static HTML for a docs page, you will most
     40        likely not have to do anything. The docs server will automatically pick
     41        up changes to the JSON or IDL schemas.
     42 
     43      - Otherwise, they will be in chrome/common/extensions/docs/templates/.
     44        See the "Overview of directories" section for more information.
     45        Chances are you'll want to change a file in either "intros" (if changing
     46        API documentation) or "articles" (if changing non-API documentation).
     47        If adding files or APIs you'll also need to add something to "public".
     48 
     49      - Files in templates directory use the Motemplate template language. It is
     50        extremely simple, essentially: write HTML.
     51        See third_party/motemplate/README.md.
     52 
     53      - static/css/out/site.css is generated by compiling static/sass/*.scss
     54        files. Don't change site.css directly. Instead, change the *.scss files
     55        and run compass from this (docs/) directory:
     56            compass compile .
     57        See http://compass-style.org/install to install compass.
     58        See https://codereview.chromium.org/238303002/#msg6 for configuration
     59        information (config.rb).
     60 
     61   2. Run 'server2/preview.py'
     62 
     63   3. Check your work at http://localhost:8000/(apps|extensions)/<doc_name>
     64 
     65   4. Upload patch and offer reviewers a preview link at a URL with your patch
     66      number and files, similar to:
     67      https://chrome-apps-doc.appspot.com/_patch/12345678/apps/index.html
     68      https://chrome-apps-doc.appspot.com/_patch/12345678/extensions/index.html
     69 
     70   5. Commit files as with any other Chrome change. The live server will update
     71      within 5-10 minutes.
     72 
     73 
     74 -----------------------
     75 Overview of directories
     76 
     77 * examples: The source for the sample extensions. Note that the sample apps are
     78   checked into github at https://github.com/GoogleChrome/chrome-app-samples.
     79 
     80 * server2: The Python AppEngine server which serves all the content (living at
     81   developer.chrome.com). Unless you're developing the server itself, you won't
     82   need to worry about this (and if you are, see the README in there).
     83 
     84 * static: The static content (images, CSS, JavaScript, etc).
     85 
     86 * templates: These are the templates that server2 interprets and generates HTML
     87   content with. This has four subdirectories:
     88     - intros: The static content that appears before the API reference on API
     89               pages.
     90     - articles: The static content that appears on non-API pages.
     91     - public: The top level templates for all pages.
     92     - private: Helper templates used in rendering the docs.
     93 
     94 
     95 --------------------
     96 The AppEngine server
     97 
     98 See server2/README.
     99