1b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy# HOW TO UPDATE SOURCE.ANDROID.COM # 2991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 3b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyThe source.android.com site contains tutorials, references, and other 4b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyinformation related to the Android Open Source Project (AOSP). The rendered 5b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyoutput of this site is static HTML, although the source contents are stored 6b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyin Javadoc. Conduct your edits in the Javadoc (.jd files). 7991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 8b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyNote that the currently viewable docs at http://source.android.com/ 9b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyare not necessarily exactly in sync with the doc sources you can download from 10b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyAOSP. If you want to make a contribution to the doc sources, please check in at 11b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyandroid-contrib@ group. That way, we can make sure the affected docs are stable 12b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphybefore you upload your CL. 13991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 14b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy### File Location ### 15991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 16b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyThe source.android.com source files are stored in the platform/docs/source.android.com/ 17b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyAndroid project: 18b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyhttps://android.googlesource.com/platform/docs/source.android.com/ 19991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 20b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyThe files to be edited are located in: <root>/docs/source.android.com/src 21991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 22b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyEvery .jd file under src/ is an individual page in Javadoc format. This format 23b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyclosely resembles HTML with different headers. 24991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 25b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphySubdirectories exist for the tabs of source.android.com with their structure 26b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyroughly (but not identically) mirroring navigation of the site. 27991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 28b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyIn addition, each tab and subdirectory contains a *_toc.cs file (such as 29b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphydevices_toc.cs) that defines the navigation for that section of the site. When 30b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphypages are added or removed, the corresponding *_toc.cs file must be updated to 31b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphymatch. 32f781f801442d9996fbb7e0c921ae6947df0abb7dDan Morrill 33f781f801442d9996fbb7e0c921ae6947df0abb7dDan Morrill### Dependencies ### 34f781f801442d9996fbb7e0c921ae6947df0abb7dDan Morrill 35b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy - Vi, Emacs or another plain-text editor 36b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy - Python 37b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy - App Engine - https://developers.google.com/appengine/ 38b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy - An app.yaml configuration file placed in the root of the 39b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy out/target/common/docs/online-sac directory with these contents: 40b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy ----- 41b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy application: NAMEOFYOURAPP 42b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy version: 1 43b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy runtime: python 44b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy api_version: 1 45f781f801442d9996fbb7e0c921ae6947df0abb7dDan Morrill 46b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy handlers: 47b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy - url: / 48b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy static_dir: / 49b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy ----- 50f781f801442d9996fbb7e0c921ae6947df0abb7dDan Morrill 51b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy## Edit Instructions ## 52a049ddecd56271b06d32448c83ddfa5914e29766Jeff Brown 53b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy1. Initialize the repository and download the Android source per: 54b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyhttp://source.android.com/source/downloading.html 55f781f801442d9996fbb7e0c921ae6947df0abb7dDan Morrill 56b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy2. Start a temporary branch for your changes, such as: 57b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyhttp://source.android.com/source/using-repo.html#start 58991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 59b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy3. Edit the Javadoc file(s) and save your changes. 60991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 61b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy4. If a page was added or removed, update the corresponding *.toc.cs file to 62b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyreflect the change. 63991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 64b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy5. Run the following make command from the root of the project parent directory: 65991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 66b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy make online-sac-docs 67991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 68b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyThis generates the output in: 69b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy<root>/out/target/common/docs/online-sac 70991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 71b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy6. Start App Engine and point it at the output directory, like so: 72991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 73b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy python /bin/google_appengine/dev_appserver.py \ 74b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy /master/out/target/common/docs/online-sac \ 75b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy --address 0.0.0.0 --port 8080 & 76991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 77b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy7. Review your changes at localhost:8080/index.html 78991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 79b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphy8. Once satisfied, submit the changes as described at: 80b339f4fe30e58a2376650b0ffa3d95572f79f970Clay Murphyhttp://source.android.com/source/submit-patches.html 81991ae4d81f940d665370e3217ec7cf3d7285ec8dSkyler Kaufman 82b339f4fe30e58a2376650b0ffa3d95572f79f970Clay MurphyYour change will be routed to the source.android.com team for inclusion. 8344436912beb88a9bdc0e45a8dcd054603a2947d9Skyler Kaufman 84