The docgen tool takes in a file or directory as input and produces documentation for all
.dart file it finds as YAML or JSON files. This outputs information about all classes, variables, functions, and methods defined in the library and its imported libraries.
The viewer uses YAML files generated by the docgen package as the data being displayed. These files are stored in Google Cloud Storage.
python upload_docgen.pyto generate these files and upload them to Cloud Storage as a new version.
These tasks can be done separately if necessary:
YAML files can be generated using the docgen package in the dart repository.
dart docgen.dart [OPTIONS] <path to directory or file>
--helpPrints help and usage information.
--verboseOutput more logging information.
--[no-]jsonOutputs to JSON. Files are outputted to YAML by default. If
--appendis used, it takes the file-format of the previous run stated in library_list.json ignoring the flag.
--include-privateFlag to include private declarations.
--include-sdkFlag to parse SDK Library files imported.
--parse-sdkParses the SDK libraries only. (Ignores the path passed in.)
--package-rootSets the package root of the library being analyzed.
--appendAppends to the docs folder, library_list.json, and index.txt.
--introductionAdds the provided markdown text file as the introduction for the outputted documentation.
Documented libraries will be located at bin/docs in either YAML or JSON format depending on options specified. There will also be a library_list.json, containing a list of all the libraries inside the docs folder.
To get more information on how to use the outputted documentation with dartdoc-viewer, please take a look at the dartdoc-viewer documentation.
To push new files to Google Cloud Storage for use by the viewer, use the
gsutil tool located at third_party/gsutil/gsutil in the Dart repository.
python gsutil -m cp -q -a public-read -r <folder> gs://dartlang-docgento upload the specified folder to the viewer's bucket. Be sure to also upload a new VERSION file if the uploaded folder is to be used.**
**Note that the bucket contains several numbered folders for each version of the documentation. Run
python gsutil ls gs://dartlang-docgen to see the file layout. Follow this convention and update a new VERSION file when uploading a new version of documentation. You can see the format of the VERSION file by running
python gsutil cat gs://dartlang-docgen/VERSION.
Docgen's generated YAML files can be used by the Dart Documentation Viewer for easy viewing and navigation through a project.
dartdoc.py script located in the
bin directory is a useful tool for creating documentation for a Dart project and running it locally.
dartdoc.py script makes use of the Google App Engine SDK for Python's development server to serve the documentation viewer. Install a recent version of the SDK before running
The following options are the most used:
python dartdoc.py --gae-sdk=<path to SDK> --options=<path to files> --options=--parse-sdk --options='--include-sdk <path to files>' --options='--append <path to files>'
python dartdoc.py -h from the
bin directory for all available options. The two required options are as follows:
--optionsoption describes any options being passed into
docgen.dart. If more then one option is desired, separate the options with a space (ex.
--gae-sdkoption gives the absolute path to the Google App Engine SDK.
python dartdoc.py --options=<docgen options> --gae-sdk=<path to SDK> will serve files generated by
docgen.dart in your browser.