| commit | e4fab172cf5b85984ffd3fa463586515573d40f4 | [log] [tgz] |
|---|---|---|
| author | keertip <keertip@google.com> | Wed Jan 06 16:59:57 2016 -0800 |
| committer | keertip <keertip@google.com> | Wed Jan 06 17:04:29 2016 -0800 |
| tree | 7a0753fd020f13a3573dccbe4f90a1df2fd0a317 | |
| parent | 8b4d154981eef4504e89b7484c201f561f3ac0a2 [diff] |
publish 0.8.5
Use dartdoc to generate HTML documentaton for your Dart package.
Note: As of Dart 1.12, dartdoc is shipped with the Dart SDK and replaces the older docgen tool.
If you want to contribute to the dartdoc project, see the contributor docs. This page contains information about using the dartdoc tool.
Download the Dart SDK, version 1.12-dev.5.10 or later. If not already added, add the SDK's bin directory to your PATH.
You can install the latest version of dartdoc with pub:
$ pub global activate dartdoc
Note: to ensure that this version is run when you type dartdoc on the command line, make sure that ~/.pub-cache/bin is on your PATH, and before the path to the Dart SDK.
Run dartdoc from the root directory of package. For example:
$ dartdoc Generating documentation for 'server_code_lab' into <path-to-server-code-lab>/server_code_lab/doc/api/ parsing lib/client/piratesapi.dart... parsing lib/common/messages.dart... parsing lib/common/utils.dart... parsing lib/server/piratesapi.dart... Parsed 4 files in 8.1 seconds. generating docs for library pirate.messages from messages.dart... generating docs for library pirate.server from piratesapi.dart... generating docs for library pirate.utils from utils.dart... generating docs for library server_code_lab.piratesApi.client from piratesapi.dart... Documented 4 libraries in 9.6 seconds. Success! Docs generated into <path-to-server-code-lab>/server_code_lab/doc/api/index.html
By default, the documentation is generated to the doc/api directory as static HTML files.
You can view the generated docs directly from the file system, but if you want to use the search function, you must load them with an HTTP server.
An easy way to run an HTTP server locally is to use the dhttpd package. For example:
$ pub global activate dhttpd $ dhttpd --path doc/api
Navigate to http://localhost:8080 in your browser; the search function should now work.
dartdoc produces static files with a predictable link structure.
index.html # homepage
index.json # machine-readable index
library-name/ # : is turned into a - e.g. dart:core => dart-core
ClassName-class.html # "homepage" for a class (and enum)
ClassName/
ClassName.html # constructor
ClassName.namedConstructor.html # named constructor
method.html
property.html
CONSTANT.html
property.html
top-level-function.html
File names are case-sensitive.
Command-line options for dartdoc include:
-h or --help Display help.--header=<file> Insert the specified file, which contains HTML code, into the header of every page.--footer=<file> Insert the specified file, which contains HTML code, into the footer of every page.--input=<directory> Generate the docs from the specified directory. If not specified, it defaults to the current directory.--output=<directory> Generate the output to the specified directory. If not specified, it defaults to doc/api.--package-root=<directory> Specify the package root of the library.--exclude=<lib1,lib2,lib3,...> Exclude the specified libraries from the generated docs.--include=<lib1,lib2,lib3,...> Generate docs for the specified libraries.--hosted-url=<url> Build a docs sitemap using the specified URL for your website.--add-crossdart Add links to Crossdart to the Source Code sections.The following options are used only when generating docs for the Dart SDK.
--dart-sdk=<path> Specify the location of the Dart SDK, if it can't be detected automatically.--sdk-docs Generate only docs for the Dart SDK.--sdk-readme=<file> Specify the README file for the Dart SDK.dartdoc will not generate documentation for a Dart element and its children that has the <nodoc> tag in the documentation comment.
Please file reports on the GitHub Issue Tracker.
Please see the dartdoc license.