README
1# HOW TO UPDATE SOURCE.ANDROID.COM #
2
3The source.android.com site contains tutorials, references, and other
4information related to the Android Open Source Project (AOSP). The rendered
5output of this site is static HTML, although the source contents are stored
6in Javadoc. Conduct your edits in the Javadoc (.jd files).
7
8Note that the currently viewable docs at http://source.android.com/
9are not necessarily exactly in sync with the doc sources you can download from
10AOSP. If you want to make a contribution to the doc sources, please check in at
11android-contrib@ group. That way, we can make sure the affected docs are stable
12before you upload your CL.
13
14### File Location ###
15
16The source.android.com source files are stored in the platform/docs/source.android.com/
17Android project:
18https://android.googlesource.com/platform/docs/source.android.com/
19
20The files to be edited are located in: <root>/docs/source.android.com/src
21
22Every .jd file under src/ is an individual page in Javadoc format. This format
23closely resembles HTML with different headers.
24
25Subdirectories exist for the tabs of source.android.com with their structure
26roughly (but not identically) mirroring navigation of the site.
27
28In addition, each tab and subdirectory contains a *_toc.cs file (such as
29devices_toc.cs) that defines the navigation for that section of the site. When
30pages are added or removed, the corresponding *_toc.cs file must be updated to
31match.
32
33### Dependencies ###
34
35 - Vi, Emacs or another plain-text editor
36 - Python
37 - App Engine - https://developers.google.com/appengine/
38 - An app.yaml configuration file placed in the root of the
39 out/target/common/docs/online-sac directory with these contents:
40 -----
41 application: NAMEOFYOURAPP
42 version: 1
43 runtime: python
44 api_version: 1
45
46 handlers:
47 - url: /
48 static_dir: /
49 -----
50
51## Edit Instructions ##
52
531. Initialize the repository and download the Android source per:
54http://source.android.com/source/downloading.html
55
562. Start a temporary branch for your changes, such as:
57http://source.android.com/source/using-repo.html#start
58
593. Edit the Javadoc file(s) and save your changes.
60
614. If a page was added or removed, update the corresponding *.toc.cs file to
62reflect the change.
63
645. Run the following make command from the root of the project parent directory:
65
66 make online-sac-docs
67
68This generates the output in:
69<root>/out/target/common/docs/online-sac
70
716. Start App Engine and point it at the output directory, like so:
72
73 python /bin/google_appengine/dev_appserver.py \
74 /master/out/target/common/docs/online-sac \
75 --address 0.0.0.0 --port 8080 &
76
777. Review your changes at localhost:8080/index.html
78
798. Once satisfied, submit the changes as described at:
80http://source.android.com/source/submit-patches.html
81
82Your change will be routed to the source.android.com team for inclusion.
83
84