Working on API docs

This is an early draft of instructions on how to work on the AngularDart (angular2 package) API docs.

• Setting up your repos
• Updating examples
• Adding examples
  • Existing webdev examples
  • Other examples
  • Troubleshooting
• Generating API docs

Setting up your repos

$ cd site-webdev
$ ./scripts/get-ng-repo.sh 
Setting environment variables from scripts/env-set.sh 
GETTING Angular from GitHub ...
+ git clone https://github.com/dart-lang/angular2.git ../angular2
Cloning into '../angular2'...
remote: Counting objects: 8438, done.
remote: Compressing objects: 100% (26/26), done.
remote: Total 8438 (delta 3), reused 0 (delta 0), pack-reused 8412
Receiving objects: 100% (8438/8438), 2.21 MiB | 863.00 KiB/s, done.
Resolving deltas: 100% (6433/6433), done.
+ git -C ../angular2 fetch origin refs/tags/
fatal: Invalid refspec 'refs/tags/'

(I see no angular-dart!!)

$ cd ..
$ ln -s angular2 angular-dart
$ git clone [email protected]:chalin/api_doc_updater.git

Updating examples

$ cd site-webdev
$ script env-set.sh
$ gulp create-example-fragments --fast
$ cd ../angular2
$ dart ../api_doc_updater/bin/api_doc_updater.dart -p doc/api/_fragments/ -i lib
Processed 350 Dart files: 2 out of 33 fragments needed updating.

Adding examples

https://github.com/chalin/api_doc_updater has docs for how to include examples.

Basically, you write the doc, and you include a reference to the example (no need to add the code):

/// ```dart
/// // {@source "docs/attribute-directives/lib/highlight_directive_1.dart"}
/// ```

Then "update" the example:

dart ../api_doc_updater/bin/api_doc_updater.dart -p doc/api/_fragments/ -i lib

Existing webdev examples

Path must start with docs. E.g., if it's under ./public/docs/_examples/template-syntax, the path starts with docs/template-syntax.

To get the path... [PENDING: give rules for finding the path. Do NOT include dart/ in the path!]

Other examples

If it's not from the webdev repo, then add it to the angular2_api_examples repo. [PENDING: check]

If it's not in any repo, use a @disabled-source tag.

Troubleshooting

If api_doc_updater has an unhandled exception like this:

Unhandled exception:
Could not load "file:///Users/kathyw/GITHUB/angular/api_doc_updater/bin/api_doc_updater.dart": FileSystemException: Cannot open file, path = '/Users/kathyw/GITHUB/angular/api_doc_updater/bin/api_doc_updater.dart' (OS Error: No such file or directory, errno = 2)

Check the path. Did you put dart/ in it? You shouldn't!

Generating API docs

The following commands remove the publish folder, then remove generated API docs and build then site. Finally, they serve the site.

$ gulp clean && gulp build --clean; ./scripts/serve_local.sh