Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / docs / source.android.com / 48289c61e03dd41c7f7a39bd1ae6fcebd5ed36da / . / README
blob: 77a76b838067d939c878caf7ce5875e7a20603a4 [file] [log] [blame]
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]1# HOW TO UPDATE SOURCE.ANDROID.COM #
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]2
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]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).
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]7
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]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.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]13
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]14### File Location ###
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]15
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]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/
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]19
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]20The files to be edited are located in: <root>/docs/source.android.com/src
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]21
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]22Every .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 -0700[diff] [blame]24
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]25Subdirectories 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 -0700[diff] [blame]27
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]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.
Dan Morrillf781f802011-04-12 16:52:23 -0700[diff] [blame]32
33### Dependencies ###
34
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]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
Dan Morrillf781f802011-04-12 16:52:23 -0700[diff] [blame]45
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]46 handlers:
47 - url: /
48 static_dir: /
49 -----
Dan Morrillf781f802011-04-12 16:52:23 -0700[diff] [blame]50
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]51## Edit Instructions ##
Jeff Browna049dde2011-06-29 16:51:54 -0700[diff] [blame]52
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]531. Initialize the repository and download the Android source per:
54http://source.android.com/source/downloading.html
Dan Morrillf781f802011-04-12 16:52:23 -0700[diff] [blame]55
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]562. 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 -0700[diff] [blame]58
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]593. Edit the Javadoc file(s) and save your changes.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]60
Collin El-Hossariba472e92015-02-03 16:44:00 -0800[diff] [blame]614. If a page was added or removed, update the corresponding _toc.cs file to
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]62reflect the change.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]63
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]645. Run the following make command from the root of the project parent directory:
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]65
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]66 make online-sac-docs
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]67
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]68This generates the output in:
69<root>/out/target/common/docs/online-sac
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]70
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]716. Start App Engine and point it at the output directory, like so:
Skyler Kaufman44436912011-04-07 15:11:52 -0700[diff] [blame]72
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]73 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 -0700[diff] [blame]76
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]777. Review your changes at localhost:8080/index.html
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]78
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]798. Once satisfied, submit the changes as described at:
80http://source.android.com/source/submit-patches.html
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]81
Clay Murphyb339f4f2013-11-12 15:22:14 -0800[diff] [blame]82Your change will be routed to the source.android.com team for inclusion.
Skyler Kaufman991ae4d2011-04-07 12:30:41 -0700[diff] [blame]83