Files

T

janicejl@google.com b734eed591 added a warning if no package root is passed in for a single file.

R=rnystrom@google.com

Review URL: https://codereview.chromium.org//21131009

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@25629 260f80e4-7a28-3924-810f-c04153c831b5

2013-07-30 18:42:56 +00:00

bin

Added a flag --append to docgen.

2013-07-30 16:56:57 +00:00

example

"Reverting 24208"

2013-06-19 23:40:17 +00:00

lib

added a warning if no package root is passed in for a single file.

2013-07-30 18:42:56 +00:00

test

Moved deleting directory to whenComplete

2013-07-26 18:04:24 +00:00

pubspec.yaml

Rename "pathos" package to "path".

2013-07-12 17:54:48 +00:00

README.md

Modified README for docgen.

2013-07-15 22:42:17 +00:00

README.md

docgen

A documentation generator for Dart.

The docgen tool takes in a file or directory as input and produces documentation for all .dart file it finds as YAML or JSON files. This outputs information about all classes, variables, functions, and methods defined in the library and its imported libraries.

Generating Files & Uploading to Cloud Storage

The viewer uses YAML files generated by the docgen package as the data being displayed. These files are stored in Google Cloud Storage.

Run python upload_docgen.py to generate these files and upload them to Cloud Storage as a new version.

These tasks can be done separately if necessary:

Generating YAML Files

YAML files can be generated using the docgen package in the dart repository.

Usage

Run dart docgen.dart [OPTIONS] <path to directory or file>

Options available

-h, --help Prints help and usage information.
-v, --verbose Output more logging information.
-j, --[no-]json Outputs to JSON. Files are outputted to YAML by default.
--include-private Flag to include private declarations.
--include-sdk Flag to parse SDK Library files imported.
--parse-sdk Parses the SDK libraries only. (Ignores the path passed in.)
--package-root Sets the package root of the library being analyzed.

Output Directory

Documented libraries will be located at bin/docs in either YAML or JSON format depending on options specified. There will also be a library_list.txt, containing a list of all the libraries inside the docs folder.

To get more information on how to use the outputted documentation with dartdoc-viewer, please take a look at the dartdoc-viewer documentation.

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.