Chromium Code Reviews Chromium Code Reviews
Issue 19070003:
Modified README for docgen. (Closed)
Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart| OLD | NEW |
|---|---|
| 1 docgen | |
| 2 ====== | |
| 3 | |
| 1 A documentation generator for Dart. | 4 A documentation generator for Dart. |
| 5 - - - | |
| 6 The docgen tool takes in file or directory as input and produces documentation | |
|
Bob Nystrom
2013/07/15 22:19:42
"in file" -> "in a file"
| |
| 7 for all `.dart` file it finds as YAML or JSON files. This outputs information | |
| 8 about all classes, variables, functions, and methods defined in the library and | |
| 9 its imported libraries. | |
| 2 | 10 |
| 3 The docgen tool takes in a library as input and produces documentation | 11 ### Generating Files & Uploading to Cloud Storage |
| 4 for it as well as all libraries it imports and uses. | |
| 5 | 12 |
| 6 This outputs information about all classes, variables, functions, and | 13 The viewer uses YAML files generated by the docgen package as the data |
| 7 methods defined in the library and its imported libraries. | 14 being displayed. These files are stored in Google Cloud Storage. |
| 8 | 15 |
| 9 ## USAGE | 16 - Run `python upload_docgen.py` to generate these files and upload them to |
| 17 Cloud Storage as a new version. | |
| 18 - - - | |
| 19 These tasks can be done separately if necessary: | |
| 10 | 20 |
| 11 dart docgen.dart path/to/file.dart | 21 ##### |
| 22 | |
| 23 #### Generating YAML Files | |
| 24 | |
| 25 YAML files can be generated using the docgen package in the dart repository. | |
| 26 | |
| 27 ###### Usage | |
| 28 | |
| 29 Run `dart docgen.dart [OPTIONS] <path to directory or file>` | |
| 30 | |
| 31 ###### Options available | |
| 32 | |
| 33 - `-h`, `--help` Prints help and usage information. | |
| 34 - `-v`, `--verbose` Output more logging information. | |
| 35 - `-j`, `--[no-]json` Outputs to JSON. Files are outputted to YAML by default. | |
| 36 - `--include-private` Flag to include private declarations. | |
| 37 - `--include-sdk` Flag to parse SDK Library files imported. | |
| 38 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) | |
| 39 - `--package-root` Sets the package root of the library being analyzed. | |
| 40 | |
| 41 ###### Output Directory | |
| 42 Documented libraries will be located at bin/docs in either YAML or JSON format d epending on options specified. There will also be a library_list.txt, | |
|
Bob Nystrom
2013/07/15 22:19:42
Long lines here and below. Wrap before 80 chars, p
| |
| 43 containing a list of all the libraries inside the docs folder. | |
| 44 | |
| 45 To get more information on how to use the outputted documentation with dartdoc-v iewer, please look at the [dartdoc-viewer documentation][dartdoc-viewer]. | |
| 46 | |
| 47 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" | |
| 48 | |
| 49 #### Uploading to Cloud Storage | |
| 50 | |
| 51 To push new files to Google Cloud Storage for use by the viewer, use the | |
| 52 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. | |
| 53 | |
| 54 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen` | |
| 55 to upload the specified folder to the viewer's bucket. Be sure to also upload | |
| 56 a new VERSION file if the uploaded folder is to be used.** | |
| 57 | |
| 58 **Note that the bucket contains several numbered folders for each version of | |
| 59 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file | |
| 60 layout. Follow this convention and update a new VERSION file when uploading | |
| 61 a new version of documentation. You can see the format of the VERSION file | |
| 62 by running `python gsutil cat gs://dartlang-docgen/VERSION`. | |
| OLD | NEW |
