Home | History | Annotate | Download | only in source.android.com 
      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