README

# HOW TO UPDATE SOURCE.ANDROID.COM #

The source.android.com site contains tutorials, references, and other
information related to the Android Open Source Project (AOSP). The rendered
output of this site is static HTML, although the source contents are stored
in Javadoc. Conduct your edits in the Javadoc (.jd files).

Note that the currently viewable docs at http://source.android.com/
are not necessarily exactly in sync with the doc sources you can download from
AOSP. If you want to make a contribution to the doc sources, please check in at
android-contrib@ group. That way, we can make sure the affected docs are stable
before you upload your CL.

### File Location ###

The source.android.com source files are stored in the platform/docs/source.android.com/
Android project:
https://android.googlesource.com/platform/docs/source.android.com/

The files to be edited are located in: <root>/docs/source.android.com/src

Every .jd file under src/ is an individual page in Javadoc format. This format
closely resembles HTML with different headers.

Subdirectories exist for the tabs of source.android.com with their structure
roughly (but not identically) mirroring navigation of the site.

In addition, each tab and subdirectory contains a *_toc.cs file (such as
devices_toc.cs) that defines the navigation for that section of the site. When
pages are added or removed, the corresponding *_toc.cs file must be updated to
match.

### Dependencies ###

 - Vi, Emacs or another plain-text editor
 - Python
 - App Engine - https://developers.google.com/appengine/
 - An app.yaml configuration file placed in the root of the
   out/target/common/docs/online-sac directory with these contents:
   -----
   application: NAMEOFYOURAPP
   version: 1
   runtime: python
   api_version: 1

   handlers:
   - url: /
     static_dir: /
   -----

## Edit Instructions ##

1. Initialize the repository and download the Android source per:
http://source.android.com/source/downloading.html

2. Start a temporary branch for your changes, such as:
http://source.android.com/source/using-repo.html#start

3. Edit the Javadoc file(s) and save your changes.

4. If a page was added or removed, update the corresponding _toc.cs file to
reflect the change.

5. Run the following make command from the root of the project parent directory:

    make online-sac-docs

This generates the output in:
<root>/out/target/common/docs/online-sac

6. Start App Engine and point it at the output directory, like so:

    python /bin/google_appengine/dev_appserver.py \ 
    /master/out/target/common/docs/online-sac \
    --address 0.0.0.0 --port 8080 &

7. Review your changes at localhost:8080/index.html

8. Once satisfied, submit the changes as described at:
http://source.android.com/source/submit-patches.html

Your change will be routed to the source.android.com team for inclusion.