OLD | NEW |
| (Empty) |
1 docgen | |
2 ====== | |
3 | |
4 **Deprecated** please use https://pub.dartlang.org/packages/dartdoc instead. | |
5 | |
6 A documentation generator for Dart. | |
7 | |
8 - - - | |
9 The docgen tool takes in a file or directory as input and produces documentation | |
10 for all `.dart` file it finds as YAML or JSON files. This outputs information | |
11 about all classes, variables, functions, and methods defined in the library and | |
12 its imported libraries. | |
13 | |
14 ### Quick Start: Common Commands | |
15 | |
16 ##### To only generate documentation, while standing in the `bin` directory: | |
17 | |
18 `dartdoc.py` generates all documentation and runs a local server with your html | |
19 pages. | |
20 | |
21 `dartdoc.py -d` ONLY generates documentation for the SDK and all packages (no | |
22 html pages generated and no server). | |
23 | |
24 `dartdoc.py -d -o package/to/document` ONLY generates documenation for the | |
25 specified package. | |
26 | |
27 ##### To generate documentation and view it through the webpage: | |
28 - Install [Google App Engine SDK for Python][GAE] (one time setup) and agree to | |
29 add symlinks so that dev\_appserver.py can be found on your PATH. | |
30 - Run `dartdoc.py`. | |
31 | |
32 ### Generating files & uploading to Cloud Storage | |
33 | |
34 The viewer uses YAML files generated by the docgen package as the data | |
35 being displayed. These files are stored in Google Cloud Storage. | |
36 | |
37 - Run `python upload_docgen.py` to generate these files and upload them to | |
38 Cloud Storage as a new version. | |
39 - - - | |
40 These tasks can be done separately if necessary: | |
41 | |
42 ##### | |
43 | |
44 #### Generating YAML files | |
45 | |
46 YAML files can be generated using the docgen package in the dart repository. | |
47 | |
48 ###### Usage | |
49 | |
50 Run `dart docgen.dart [OPTIONS] <path to directory or file>` | |
51 | |
52 ###### Options available | |
53 | |
54 - `-h`, `--help` Prints help and usage information. | |
55 - `-v`, `--verbose` Output more logging information. | |
56 - `-j`, `--[no-]json` Outputs to JSON. Files are outputted to YAML by default. | |
57 If `--append` is used, it takes the file-format of the previous run stated in | |
58 library_list.json ignoring the flag. | |
59 - `--include-private` Flag to include private declarations. | |
60 - `--include-sdk` Flag to parse SDK Library files imported. | |
61 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) | |
62 - `--package-root` Sets the package root of the library being analyzed. | |
63 - `--append` Appends to the docs folder, library_list.json, and index.txt. | |
64 - `--introduction` Adds the provided markdown text file as the introduction | |
65 for the outputted documentation. | |
66 | |
67 | |
68 ###### Output directory | |
69 Documented libraries will be located at bin/docs in either YAML or JSON format | |
70 depending on options specified. There will also be a library\_list.json, | |
71 containing a list of all the libraries inside the docs folder. | |
72 | |
73 To get more information on how to use the outputted documentation with | |
74 dartdoc-viewer, please take a look at the | |
75 [dartdoc-viewer documentation][dartdoc-viewer]. | |
76 | |
77 #### Uploading to Cloud Storage | |
78 | |
79 To push new files to Google Cloud Storage for use by the viewer, use the | |
80 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. | |
81 | |
82 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen` | |
83 to upload the specified folder to the viewer's bucket. Be sure to also upload | |
84 a new VERSION file if the uploaded folder is to be used.** | |
85 | |
86 **Note that the bucket contains several numbered folders for each version of | |
87 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file | |
88 layout. Follow this convention and update a new VERSION file when uploading | |
89 a new version of documentation. You can see the format of the VERSION file | |
90 by running `python gsutil cat gs://dartlang-docgen/VERSION`. | |
91 | |
92 ### Viewing generated documentation | |
93 | |
94 Docgen's generated YAML files can be used by the | |
95 [Dart Documentation Viewer][dartdoc-viewer] for easy viewing and navigation | |
96 through a project. | |
97 | |
98 --- | |
99 | |
100 #### Using dartdoc.py | |
101 | |
102 The `dartdoc.py` script located in the `bin` directory is a useful tool for | |
103 creating documentation for a Dart project and running it locally. | |
104 | |
105 ##### Setup | |
106 | |
107 The `dartdoc.py` script makes use of the | |
108 [Google App Engine SDK for Python][GAE]'s development server to serve the | |
109 documentation viewer. Install a recent version of the SDK before running | |
110 `dartdoc.py`. | |
111 | |
112 ##### Running dartdoc.py | |
113 | |
114 ######Common Options | |
115 | |
116 The following options are the most used: | |
117 | |
118 python dartdoc.py --gae-sdk=<path to SDK> | |
119 --options=<path to files> | |
120 --options=--parse-sdk | |
121 --options='--include-sdk <path to files>' | |
122 --options='--append <path to files>' | |
123 | |
124 ######All Options | |
125 | |
126 Run `python dartdoc.py -h` from the `bin` directory for all available options. | |
127 The two required options are as follows: | |
128 | |
129 1. The `--options` option describes any options being passed into `docgen.dart`
. | |
130 If more then one option is desired, separate the options with a space | |
131 (ex. `--options='--include-sdk files'`). | |
132 2. The `--gae-sdk` option gives the absolute path to the | |
133 [Google App Engine SDK][GAE]. | |
134 | |
135 Running `python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK>` | |
136 will serve files generated by `docgen.dart` in your browser. | |
137 | |
138 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer" | |
139 [GAE]: https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_f
or_Python "Google App Engine SDK for Python" | |
140 | |
OLD | NEW |