Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(95)

Side by Side Diff: pkg/docgen/README.md

Issue 51003002: Update headings to use sentence case. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Created 7 years, 1 month ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « no previous file | pkg/html_import/README.md » ('j') | pkg/polymer_expressions/README.md » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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
OLDNEW
« no previous file with comments | « no previous file | pkg/html_import/README.md » ('j') | pkg/polymer_expressions/README.md » ('J')

Powered by Google App Engine
This is Rietveld 408576698