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

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

Issue 22488017: Added script to run local files on App Engine (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Fixed README and added more informative help information. Created 7 years, 4 months 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/docgen/bin/dartdoc.py » ('j') | pkg/docgen/bin/dartdoc.py » ('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
(...skipping 19 matching lines...) Expand all
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 - `--include-private` Flag to include private declarations. 36 - `--include-private` Flag to include private declarations.
37 - `--include-sdk` Flag to parse SDK Library files imported. 37 - `--include-sdk` Flag to parse SDK Library files imported.
38 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.) 38 - `--parse-sdk` Parses the SDK libraries only. (Ignores the path passed in.)
39 - `--package-root` Sets the package root of the library being analyzed. 39 - `--package-root` Sets the package root of the library being analyzed.
40 - `--append` Appends to the docs folder, library_list.txt, and index.txt.
40 41
41 ###### Output Directory 42 ###### Output Directory
42 Documented libraries will be located at bin/docs in either YAML or JSON format 43 Documented libraries will be located at bin/docs in either YAML or JSON format
43 depending on options specified. There will also be a library_list.txt, 44 depending on options specified. There will also be a library_list.txt,
44 containing a list of all the libraries inside the docs folder. 45 containing a list of all the libraries inside the docs folder.
45 46
46 To get more information on how to use the outputted documentation with 47 To get more information on how to use the outputted documentation with
47 dartdoc-viewer, please take a look at the 48 dartdoc-viewer, please take a look at the
48 [dartdoc-viewer documentation][dartdoc-viewer]. 49 [dartdoc-viewer documentation][dartdoc-viewer].
49 50
50 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer"
51
52 #### Uploading to Cloud Storage 51 #### Uploading to Cloud Storage
53 52
54 To push new files to Google Cloud Storage for use by the viewer, use the 53 To push new files to Google Cloud Storage for use by the viewer, use the
55 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository. 54 `gsutil` tool located at third_party/gsutil/gsutil in the Dart repository.
56 55
57 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen` 56 - Run `python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgen`
58 to upload the specified folder to the viewer's bucket. Be sure to also upload 57 to upload the specified folder to the viewer's bucket. Be sure to also upload
59 a new VERSION file if the uploaded folder is to be used.** 58 a new VERSION file if the uploaded folder is to be used.**
60 59
61 **Note that the bucket contains several numbered folders for each version of 60 **Note that the bucket contains several numbered folders for each version of
62 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file 61 the documentation. Run `python gsutil ls gs://dartlang-docgen` to see the file
63 layout. Follow this convention and update a new VERSION file when uploading 62 layout. Follow this convention and update a new VERSION file when uploading
64 a new version of documentation. You can see the format of the VERSION file 63 a new version of documentation. You can see the format of the VERSION file
65 by running `python gsutil cat gs://dartlang-docgen/VERSION`. 64 by running `python gsutil cat gs://dartlang-docgen/VERSION`.
65
66 ### Viewing Generated Documentation
67
68 Docgen's generated YAML files can be used by the
69 [Dart Documentation Viewer][dartdoc-viewer] for easy viewing and navigation
70 through a project.
71
72 ---
73
74 #### Using dartdoc.py
75
76 The `dartdoc.py` script located in the `bin` directory is a useful tool for
77 creating documentation for a Dart project and running it locally.
78
79 ##### Setup
80
81 The `dartdoc.py` script makes use of the
82 [Google App Engine SDK for Python][GAE]'s development server to serve the
83 documentation viewer. Install a recent version of the SDK before running
84 `dartdoc.py`.
85
86 ##### Running dartdoc.py
87
88 ######Common Options
89
90 The following options are the most used:
91
92 python dartdoc.py --gae-sdk=<path to SDK>
93 --options=<path to files>
94 --options=--parse-sdk
95 --options='--include-sdk <path to files>'
96 --options='--append <path to files>'
97
98 ######All Options
99
100 Run `python dartdoc.py -h` from the `bin` directory for all available options.
101 The two required options are as follows:
102
103 1. The `--options` option describes any options being passed into `docgen.dart` .
104 If more then one option is desired, separate the options with a space
105 (ex. `--options='--include-sdk files'`).
106 2. The `--gae-sdk` option gives the absolute path to the
107 [Google App Engine SDK][GAE].
108
109 Running `python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK>`
110 will serve files generated by `docgen.dart` in your browser.
111
112 [dartdoc-viewer]: https://github.com/dart-lang/dartdoc-viewer "Dartdoc-Viewer"
113 [GAE]: https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_f or_Python "Google App Engine SDK for Python"
114
OLDNEW
« no previous file with comments | « no previous file | pkg/docgen/bin/dartdoc.py » ('j') | pkg/docgen/bin/dartdoc.py » ('J')

Powered by Google App Engine
This is Rietveld 408576698