dart-api-app

The front-end Dart documentation viewer.

Here is how our tests are doing:

Generating Files & Uploading to Cloud Storage

The viewer uses YAML or JSON files generated by the docgen package at pkg/docgen/ in the Dart repository as the data being displayed. These files are stored in Google Cloud Storage.

Run python upload_docgen.py from pkg/docgen/bin in the Dart repository to generate these files and upload them to Cloud Storage as a new version.

These tasks can be done separately if necessary:

Uploading to Cloud Storage

To push new files to Google Cloud Storage for use by the viewer, use the gsutil tool located at third_party/gsutil/gsutil in the Dart repository.

• Run python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen to upload the specified folder to the viewer's bucket. Be sure to also upload a new VERSION file if the uploaded folder is to be used.**

**Note that the bucket contains several numbered folders for each version of the documentation. Run python gsutil ls gs://dartlang-docgen to see the file layout. Follow this convention and update a new VERSION file when uploading a new version of documentation. You can see the format of the VERSION file by running python gsutil cat gs://dartlang-docgen/VERSION.

Running Locally

There are two ways to run the viewer locally:

1. The dartdoc.py script in the pkg/docgen/bin directory of the Dart repository is a useful tool for generating documentation and running the viewer. Checkout the docgen README for more information on how to run it. The script makes use of the Google App Engine SDK for Python's development server. This can be used manually without the script by running dev_appserver.py <folder containing app.yaml>, but first act on the following:

• When running the viewer on the development server, YAML or JSON files are retrieved from the client/local folder instead of the client/docs folder. You must manually rename your 'docs' directory to 'local' for the server to correctly retrieve your files.
• If you intend to view documentation in a browser other than Dartium, you will first have to compile the viewer to JavaScript. This can be done by running sdk/bin/dart2js from the Dart repository on client/web/app.dart.

2. In the Dart Editor, the viewer can be run by running dart client/build.dart and then running index.html from the client/web/out/ folder. Be sure to have a working version of YAML or JSON documentation from Generating YAML Files. These files should be put in a folder named 'docs' located in the client/ folder.

Pushing to App Engine

Follow these steps to push to Google App Engine:

1. Download the Google App Engine SDK for Python and add it to your PATH.

2. Run appcfg.py update <folder containing app.yaml>.