| 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 |
| 11 ### Generating Files & Uploading to Cloud Storage | 11 ### Generating files & uploading to Cloud Storage |
| 12 | 12 |
| 13 The viewer uses YAML files generated by the docgen package as the data | 13 The viewer uses YAML files generated by the docgen package as the data |
| 14 being displayed. These files are stored in Google Cloud Storage. | 14 being displayed. These files are stored in Google Cloud Storage. |
| 15 | 15 |
| 16 - Run `python upload_docgen.py` to generate these files and upload them to | 16 - Run `python upload_docgen.py` to generate these files and upload them to |
| 17 Cloud Storage as a new version. | 17 Cloud Storage as a new version. |
| 18 - - - | 18 - - - |
| 19 These tasks can be done separately if necessary: | 19 These tasks can be done separately if necessary: |
| 20 | 20 |
| 21 ##### | 21 ##### |
| 22 | 22 |
| 23 #### Generating YAML Files | 23 #### Generating YAML files |
| 24 | 24 |
| 25 YAML files can be generated using the docgen package in the dart repository. | 25 YAML files can be generated using the docgen package in the dart repository. |
| 26 | 26 |
| 27 ###### Usage | 27 ###### Usage |
| 28 | 28 |
| 29 Run `dart docgen.dart [OPTIONS] <path to directory or file>` | 29 Run `dart docgen.dart [OPTIONS] <path to directory or file>` |
| 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 If `--append` is used, it takes the file-format of the previous run stated in | 36 If `--append` is used, it takes the file-format of the previous run stated in |
| 37 library_list.json ignoring the flag. | 37 library_list.json ignoring the flag. |
| 38 - `--include-private` Flag to include private declarations. | 38 - `--include-private` Flag to include private declarations. |
| 39 - `--include-sdk` Flag to parse SDK Library files imported. | 39 - `--include-sdk` Flag to parse SDK Library files imported. |
| 40 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) | 40 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) |
| 41 - `--package-root` Sets the package root of the library being analyzed. | 41 - `--package-root` Sets the package root of the library being analyzed. |
| 42 - `--append` Appends to the docs folder, library_list.json, and index.txt. | 42 - `--append` Appends to the docs folder, library_list.json, and index.txt. |
| 43 - `--introduction` Adds the provided markdown text file as the introduction | 43 - `--introduction` Adds the provided markdown text file as the introduction |
| 44 for the outputted documentation. | 44 for the outputted documentation. |
| 45 | 45 |
| 46 | 46 |
| 47 ###### Output Directory | 47 ###### Output directory |
| 48 Documented libraries will be located at bin/docs in either YAML or JSON format | 48 Documented libraries will be located at bin/docs in either YAML or JSON format |
| 49 depending on options specified. There will also be a library_list.json, | 49 depending on options specified. There will also be a library_list.json, |
| 50 containing a list of all the libraries inside the docs folder. | 50 containing a list of all the libraries inside the docs folder. |
| 51 | 51 |
| 52 To get more information on how to use the outputted documentation with | 52 To get more information on how to use the outputted documentation with |
| 53 dartdoc-viewer, please take a look at the | 53 dartdoc-viewer, please take a look at the |
| 54 [dartdoc-viewer documentation][dartdoc-viewer]. | 54 [dartdoc-viewer documentation][dartdoc-viewer]. |
| 55 | 55 |
| 56 #### Uploading to Cloud Storage | 56 #### Uploading to Cloud Storage |
| 57 | 57 |
| 58 To push new files to Google Cloud Storage for use by the viewer, use the | 58 To push new files to Google Cloud Storage for use by the viewer, use the |
| 59 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. | 59 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. |
| 60 | 60 |
| 61 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen` | 61 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen` |
| 62 to upload the specified folder to the viewer's bucket. Be sure to also upload | 62 to upload the specified folder to the viewer's bucket. Be sure to also upload |
| 63 a new VERSION file if the uploaded folder is to be used.** | 63 a new VERSION file if the uploaded folder is to be used.** |
| 64 | 64 |
| 65 **Note that the bucket contains several numbered folders for each version of | 65 **Note that the bucket contains several numbered folders for each version of |
| 66 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file | 66 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file |
| 67 layout. Follow this convention and update a new VERSION file when uploading | 67 layout. Follow this convention and update a new VERSION file when uploading |
| 68 a new version of documentation. You can see the format of the VERSION file | 68 a new version of documentation. You can see the format of the VERSION file |
| 69 by running `python gsutil cat gs://dartlang-docgen/VERSION`. | 69 by running `python gsutil cat gs://dartlang-docgen/VERSION`. |
| 70 | 70 |
| 71 ### Viewing Generated Documentation | 71 ### Viewing generated documentation |
| 72 | 72 |
| 73 Docgen's generated YAML files can be used by the | 73 Docgen's generated YAML files can be used by the |
| 74 [Dart Documentation Viewer][dartdoc-viewer] for easy viewing and navigation | 74 [Dart Documentation Viewer][dartdoc-viewer] for easy viewing and navigation |
| 75 through a project. | 75 through a project. |
| 76 | 76 |
| 77 --- | 77 --- |
| 78 | 78 |
| 79 #### Using dartdoc.py | 79 #### Using dartdoc.py |
| 80 | 80 |
| 81 The `dartdoc.py` script located in the `bin` directory is a useful tool for | 81 The `dartdoc.py` script located in the `bin` directory is a useful tool for |
| (...skipping 28 matching lines...) Expand all Loading... |
| 110 (ex. `--options='--include-sdk files'`). | 110 (ex. `--options='--include-sdk files'`). |
| 111 2. The `--gae-sdk` option gives the absolute path to the | 111 2. The `--gae-sdk` option gives the absolute path to the |
| 112 [Google App Engine SDK][GAE]. | 112 [Google App Engine SDK][GAE]. |
| 113 | 113 |
| 114 Running `python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK>` | 114 Running `python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK>` |
| 115 will serve files generated by `docgen.dart` in your browser. | 115 will serve files generated by `docgen.dart` in your browser. |
| 116 | 116 |
| 117 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" | 117 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" |
| 118 [GAE]: https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_f
or_Python "Google App Engine SDK for Python" | 118 [GAE]: https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_f
or_Python "Google App Engine SDK for Python" |
| 119 | 119 |
| OLD | NEW |