blob: 77a76b838067d939c878caf7ce5875e7a20603a4 [file] [log] [blame]
Clay Murphyb339f4f2013-11-12 15:22:14 -08001# HOW TO UPDATE SOURCE.ANDROID.COM #
Skyler Kaufman991ae4d2011-04-07 12:30:41 -07002
Clay Murphyb339f4f2013-11-12 15:22:14 -08003The 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).
Skyler Kaufman991ae4d2011-04-07 12:30:41 -07007
Clay Murphyb339f4f2013-11-12 15:22:14 -08008Note 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.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070013
Clay Murphyb339f4f2013-11-12 15:22:14 -080014### File Location ###
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070015
Clay Murphyb339f4f2013-11-12 15:22:14 -080016The 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/
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070019
Clay Murphyb339f4f2013-11-12 15:22:14 -080020The files to be edited are located in: <root>/docs/source.android.com/src
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070021
Clay Murphyb339f4f2013-11-12 15:22:14 -080022Every .jd file under src/ is an individual page in Javadoc format. This format
23closely resembles HTML with different headers.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070024
Clay Murphyb339f4f2013-11-12 15:22:14 -080025Subdirectories exist for the tabs of source.android.com with their structure
26roughly (but not identically) mirroring navigation of the site.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070027
Clay Murphyb339f4f2013-11-12 15:22:14 -080028In 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.
Dan Morrillf781f802011-04-12 16:52:23 -070032
33### Dependencies ###
34
Clay Murphyb339f4f2013-11-12 15:22:14 -080035 - 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
Dan Morrillf781f802011-04-12 16:52:23 -070045
Clay Murphyb339f4f2013-11-12 15:22:14 -080046 handlers:
47 - url: /
48 static_dir: /
49 -----
Dan Morrillf781f802011-04-12 16:52:23 -070050
Clay Murphyb339f4f2013-11-12 15:22:14 -080051## Edit Instructions ##
Jeff Browna049dde2011-06-29 16:51:54 -070052
Clay Murphyb339f4f2013-11-12 15:22:14 -0800531. Initialize the repository and download the Android source per:
54http://source.android.com/source/downloading.html
Dan Morrillf781f802011-04-12 16:52:23 -070055
Clay Murphyb339f4f2013-11-12 15:22:14 -0800562. Start a temporary branch for your changes, such as:
57http://source.android.com/source/using-repo.html#start
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070058
Clay Murphyb339f4f2013-11-12 15:22:14 -0800593. Edit the Javadoc file(s) and save your changes.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070060
Collin El-Hossariba472e92015-02-03 16:44:00 -0800614. If a page was added or removed, update the corresponding _toc.cs file to
Clay Murphyb339f4f2013-11-12 15:22:14 -080062reflect the change.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070063
Clay Murphyb339f4f2013-11-12 15:22:14 -0800645. Run the following make command from the root of the project parent directory:
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070065
Clay Murphyb339f4f2013-11-12 15:22:14 -080066 make online-sac-docs
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070067
Clay Murphyb339f4f2013-11-12 15:22:14 -080068This generates the output in:
69<root>/out/target/common/docs/online-sac
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070070
Clay Murphyb339f4f2013-11-12 15:22:14 -0800716. Start App Engine and point it at the output directory, like so:
Skyler Kaufman44436912011-04-07 15:11:52 -070072
Clay Murphyb339f4f2013-11-12 15:22:14 -080073 python /bin/google_appengine/dev_appserver.py \
74 /master/out/target/common/docs/online-sac \
75 --address 0.0.0.0 --port 8080 &
Skyler Kaufman44436912011-04-07 15:11:52 -070076
Clay Murphyb339f4f2013-11-12 15:22:14 -0800777. Review your changes at localhost:8080/index.html
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070078
Clay Murphyb339f4f2013-11-12 15:22:14 -0800798. Once satisfied, submit the changes as described at:
80http://source.android.com/source/submit-patches.html
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070081
Clay Murphyb339f4f2013-11-12 15:22:14 -080082Your change will be routed to the source.android.com team for inclusion.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -070083