| 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 ### Quick Start: Common Commands | 11 ### Quick Start: Common Commands |
| 12 | 12 |
| 13 While standing in the `bin` directory: | 13 ##### To only generate documentation, while standing in the `bin` directory: |
| 14 | 14 |
| 15 `dartdoc.py` generates all documentation and runs a local server with your html | 15 `dartdoc.py` generates all documentation and runs a local server with your html |
| 16 pages. | 16 pages. |
| 17 | 17 |
| 18 `dartdoc.py -d` ONLY generates documentation for the SDK and all packages (no | 18 `dartdoc.py -d` ONLY generates documentation for the SDK and all packages (no |
| 19 html pages generated and no server). | 19 html pages generated and no server). |
| 20 | 20 |
| 21 `dartdoc.py -d -o package/to/document` ONLY generates documenation for the | 21 `dartdoc.py -d -o package/to/document` ONLY generates documenation for the |
| 22 specified package. | 22 specified package. |
| 23 | 23 |
| 24 ##### To generate documentation and view it through the webpage: |
| 25 - Install [Google App Engine SDK for Python][GAE] (one time setup) and agree to |
| 26 add symlinks so that dev\_appserver.py can be found on your PATH. |
| 27 - Run `dartdoc.py`. |
| 28 |
| 24 ### Generating files & uploading to Cloud Storage | 29 ### Generating files & uploading to Cloud Storage |
| 25 | 30 |
| 26 The viewer uses YAML files generated by the docgen package as the data | 31 The viewer uses YAML files generated by the docgen package as the data |
| 27 being displayed. These files are stored in Google Cloud Storage. | 32 being displayed. These files are stored in Google Cloud Storage. |
| 28 | 33 |
| 29 - Run `python upload_docgen.py` to generate these files and upload them to | 34 - Run `python upload_docgen.py` to generate these files and upload them to |
| 30 Cloud Storage as a new version. | 35 Cloud Storage as a new version. |
| 31 - - - | 36 - - - |
| 32 These tasks can be done separately if necessary: | 37 These tasks can be done separately if necessary: |
| 33 | 38 |
| (...skipping 18 matching lines...) Expand all Loading... |
| 52 - `--include-sdk` Flag to parse SDK Library files imported. | 57 - `--include-sdk` Flag to parse SDK Library files imported. |
| 53 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) | 58 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) |
| 54 - `--package-root` Sets the package root of the library being analyzed. | 59 - `--package-root` Sets the package root of the library being analyzed. |
| 55 - `--append` Appends to the docs folder, library_list.json, and index.txt. | 60 - `--append` Appends to the docs folder, library_list.json, and index.txt. |
| 56 - `--introduction` Adds the provided markdown text file as the introduction | 61 - `--introduction` Adds the provided markdown text file as the introduction |
| 57 for the outputted documentation. | 62 for the outputted documentation. |
| 58 | 63 |
| 59 | 64 |
| 60 ###### Output directory | 65 ###### Output directory |
| 61 Documented libraries will be located at bin/docs in either YAML or JSON format | 66 Documented libraries will be located at bin/docs in either YAML or JSON format |
| 62 depending on options specified. There will also be a library_list.json, | 67 depending on options specified. There will also be a library\_list.json, |
| 63 containing a list of all the libraries inside the docs folder. | 68 containing a list of all the libraries inside the docs folder. |
| 64 | 69 |
| 65 To get more information on how to use the outputted documentation with | 70 To get more information on how to use the outputted documentation with |
| 66 dartdoc-viewer, please take a look at the | 71 dartdoc-viewer, please take a look at the |
| 67 [dartdoc-viewer documentation][dartdoc-viewer]. | 72 [dartdoc-viewer documentation][dartdoc-viewer]. |
| 68 | 73 |
| 69 #### Uploading to Cloud Storage | 74 #### Uploading to Cloud Storage |
| 70 | 75 |
| 71 To push new files to Google Cloud Storage for use by the viewer, use the | 76 To push new files to Google Cloud Storage for use by the viewer, use the |
| 72 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. | 77 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. |
| (...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 123 (ex. `--options='--include-sdk files'`). | 128 (ex. `--options='--include-sdk files'`). |
| 124 2. The `--gae-sdk` option gives the absolute path to the | 129 2. The `--gae-sdk` option gives the absolute path to the |
| 125 [Google App Engine SDK][GAE]. | 130 [Google App Engine SDK][GAE]. |
| 126 | 131 |
| 127 Running `python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK>` | 132 Running `python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK>` |
| 128 will serve files generated by `docgen.dart` in your browser. | 133 will serve files generated by `docgen.dart` in your browser. |
| 129 | 134 |
| 130 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" | 135 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" |
| 131 [GAE]: https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_f
or_Python "Google App Engine SDK for Python" | 136 [GAE]: https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_f
or_Python "Google App Engine SDK for Python" |
| 132 | 137 |
| OLD | NEW |