| OLD | NEW |
| 1 docgen | 1 docgen |
| 2 ====== | 2 ====== |
| 3 | 3 |
| 4 A documentation generator for Dart. | 4 A documentation generator for Dart. |
| 5 - - - | 5 - - - |
| 6 The docgen tool takes in a file or directory as input and produces documentation | 6 The docgen tool takes in a file or directory as input and produces documentation |
| 7 for all `.dart` file it finds as YAML or JSON files. This outputs information | 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 | 8 about all classes, variables, functions, and methods defined in the library and |
| 9 its imported libraries. | 9 its imported libraries. |
| 10 | 10 |
| (...skipping 19 matching lines...) Expand all Loading... |
| 30 | 30 |
| 31 ###### Options available | 31 ###### Options available |
| 32 | 32 |
| 33 - `-h`, `--help` Prints help and usage information. | 33 - `-h`, `--help` Prints help and usage information. |
| 34 - `-v`, `--verbose` Output more logging information. | 34 - `-v`, `--verbose` Output more logging information. |
| 35 - `-j`, `--[no-]json` Outputs to JSON. Files are outputted to YAML by default. | 35 - `-j`, `--[no-]json` Outputs to JSON. Files are outputted to YAML by default. |
| 36 - `--include-private` Flag to include private declarations. | 36 - `--include-private` Flag to include private declarations. |
| 37 - `--include-sdk` Flag to parse SDK Library files imported. | 37 - `--include-sdk` Flag to parse SDK Library files imported. |
| 38 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) | 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. | 39 - `--package-root` Sets the package root of the library being analyzed. |
| 40 - `--append` Appends to the docs folder, library_list.txt, and index.txt. |
| 40 | 41 |
| 41 ###### Output Directory | 42 ###### Output Directory |
| 42 Documented libraries will be located at bin/docs in either YAML or JSON format | 43 Documented libraries will be located at bin/docs in either YAML or JSON format |
| 43 depending on options specified. There will also be a library_list.txt, | 44 depending on options specified. There will also be a library_list.txt, |
| 44 containing a list of all the libraries inside the docs folder. | 45 containing a list of all the libraries inside the docs folder. |
| 45 | 46 |
| 46 To get more information on how to use the outputted documentation with | 47 To get more information on how to use the outputted documentation with |
| 47 dartdoc-viewer, please take a look at the | 48 dartdoc-viewer, please take a look at the |
| 48 [dartdoc-viewer documentation][dartdoc-viewer]. | 49 [dartdoc-viewer documentation][dartdoc-viewer]. |
| 49 | 50 |
| 50 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" | |
| 51 | |
| 52 #### Uploading to Cloud Storage | 51 #### Uploading to Cloud Storage |
| 53 | 52 |
| 54 To push new files to Google Cloud Storage for use by the viewer, use the | 53 To push new files to Google Cloud Storage for use by the viewer, use the |
| 55 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. | 54 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. |
| 56 | 55 |
| 57 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen` | 56 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen` |
| 58 to upload the specified folder to the viewer's bucket. Be sure to also upload | 57 to upload the specified folder to the viewer's bucket. Be sure to also upload |
| 59 a new VERSION file if the uploaded folder is to be used.** | 58 a new VERSION file if the uploaded folder is to be used.** |
| 60 | 59 |
| 61 **Note that the bucket contains several numbered folders for each version of | 60 **Note that the bucket contains several numbered folders for each version of |
| 62 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file | 61 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file |
| 63 layout. Follow this convention and update a new VERSION file when uploading | 62 layout. Follow this convention and update a new VERSION file when uploading |
| 64 a new version of documentation. You can see the format of the VERSION file | 63 a new version of documentation. You can see the format of the VERSION file |
| 65 by running `python gsutil cat gs://dartlang-docgen/VERSION`. | 64 by running `python gsutil cat gs://dartlang-docgen/VERSION`. |
| 65 |
| 66 ### Viewing Generated Documentation |
| 67 |
| 68 Docgen's generated YAML files can be used by the |
| 69 [Dart Documentation Viewer][dartdoc-viewer] for easy viewing and navigation |
| 70 through a project. |
| 71 |
| 72 --- |
| 73 |
| 74 #### Using dartdoc.py |
| 75 |
| 76 The `dartdoc.py` script located in the `bin` directory is a useful tool for |
| 77 creating documentation for a Dart project and running it locally. |
| 78 |
| 79 ##### Setup |
| 80 |
| 81 The `dartdoc.py` script makes use of the |
| 82 [Google App Engine SDK for Python][GAE]'s development server to serve the |
| 83 documentation viewer. Install a recent version of the SDK before running |
| 84 `dartdoc.py`. |
| 85 |
| 86 ##### Running dartdoc.py |
| 87 |
| 88 ######Common Options |
| 89 |
| 90 The following options are the most used: |
| 91 |
| 92 python dartdoc.py --gae-sdk=<path to SDK> |
| 93 --options=<path to files> |
| 94 --options=--parse-sdk |
| 95 --options='--include-sdk <path to files>' |
| 96 --options='--append <path to files>' |
| 97 |
| 98 ######All Options |
| 99 |
| 100 Run `python dartdoc.py -h` from the `bin` directory for all available options. |
| 101 The two required options are as follows: |
| 102 |
| 103 1. The `--options` option describes any options being passed into `docgen.dart`
. |
| 104 If more then one option is desired, separate the options with a space |
| 105 (ex. `--options='--include-sdk files'`). |
| 106 2. The `--gae-sdk` option gives the absolute path to the |
| 107 [Google App Engine SDK][GAE]. |
| 108 |
| 109 Running `python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK>` |
| 110 will serve files generated by `docgen.dart` in your browser. |
| 111 |
| 112 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" |
| 113 [GAE]: https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_f
or_Python "Google App Engine SDK for Python" |
| 114 |
| OLD | NEW |