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 |