README
1 # HOW TO UPDATE SOURCE.ANDROID.COM #
2
3 The source.android.com site contains tutorials, references, and other
4 information related to the Android Open Source Project (AOSP). The rendered
5 output of this site is static HTML, although the source contents are stored
6 in Javadoc. Conduct your edits in the Javadoc (.jd files).
7
8 Note that the currently viewable docs at http://source.android.com/
9 are not necessarily exactly in sync with the doc sources you can download from
10 AOSP. If you want to make a contribution to the doc sources, please check in at
11 android-contrib@ group. That way, we can make sure the affected docs are stable
12 before you upload your CL.
13
14 ### File Location ###
15
16 The source.android.com source files are stored in the platform/docs/source.android.com/
17 Android project:
18 https://android.googlesource.com/platform/docs/source.android.com/
19
20 The files to be edited are located in: <root>/docs/source.android.com/src
21
22 Every .jd file under src/ is an individual page in Javadoc format. This format
23 closely resembles HTML with different headers.
24
25 Subdirectories exist for the tabs of source.android.com with their structure
26 roughly (but not identically) mirroring navigation of the site.
27
28 In addition, each tab and subdirectory contains a *_toc.cs file (such as
29 devices_toc.cs) that defines the navigation for that section of the site. When
30 pages are added or removed, the corresponding *_toc.cs file must be updated to
31 match.
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
53 1. Initialize the repository and download the Android source per:
54 http://source.android.com/source/downloading.html
55
56 2. Start a temporary branch for your changes, such as:
57 http://source.android.com/source/using-repo.html#start
58
59 3. Edit the Javadoc file(s) and save your changes.
60
61 4. If a page was added or removed, update the corresponding _toc.cs file to
62 reflect the change.
63
64 5. Run the following make command from the root of the project parent directory:
65
66 make online-sac-docs
67
68 This generates the output in:
69 <root>/out/target/common/docs/online-sac
70
71 6. 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
77 7. Review your changes at localhost:8080/index.html
78
79 8. Once satisfied, submit the changes as described at:
80 http://source.android.com/source/submit-patches.html
81
82 Your change will be routed to the source.android.com team for inclusion.
83
84