commit | d834d1a47a96046e0369c4573486ddce50a30fa6 | [log] [tgz] |
---|---|---|
author | Greg Spencer <gspencergoog@users.noreply.github.com> | Thu May 24 10:15:41 2018 -0700 |
committer | jcollins-g <jcollins@google.com> | Thu May 24 10:15:41 2018 -0700 |
tree | dbb701cac21ce3a8a3ee1d18bb77e0c97abfd649 | |
parent | 37273d8452378a774957c65f496ca8dd0c997086 [diff] |
Adding animation directive for injecting animated diagrams (#1698) * Adding animation directive for injecting animated diagrams * Updated Testing Goldens * Adding two more tests, updating goldens again
Use dartdoc
to generate HTML documentaton for your Dart package.
For information about contributing to the dartdoc project, see the contributor docs.
For issues/details related to hosted Dart API docs, see dart-lang/api.dartlang.org.
bin
directory to your PATH
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.
Run dartdoc -h
to see the available command-line options.
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.
Check out the Effective Dart: Documentation guide.
The guide covers formatting, linking, markup, and general best practices when authoring doc comments for Dart with dartdoc
.
dartdoc
will not generate documentation for a Dart element and its children that have the @nodoc
tag in the documentation comment.
Creating a file named dartdoc_options.yaml at the top of your package can change how Dartdoc generates docs.
dartdoc: categoryOrder: ["First Category", "Second Category"] linkTo: url: "https://my.dartdocumentationsite.org/dev/%v%"
Unrecognized options will be ignored. Supported options:
url: A string indicating the base URL for documentation of this package. Ordinarily you do not need to set this in the package: consider --link-to-hosted and --link-to-sdks instead of this option if you need to build your own website with dartdoc.
The following strings will be substituted in to complete the URL:
%b%
: The branch as indicated by text in the version. 2.0.0-dev.3 is branch “dev”. No branch is considered to be “stable”.%n%
: The name of this package, as defined in pubspec.yaml.%v%
: The version of this package as defined in pubspec.yaml.The following are experimental options whose semantics are in flux and may be buggy. If you use one, please keep a close eye on the changing semantics. In general, paths are relative to the directory the dartdoc_options.yaml the option is defined in and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows.
You can tag libraries in their documentation with the string {@category YourCategory}
, and that will cause the library to appear in a category when showing the sidebar on the Package and Library pages.
/// Here is my library. /// /// {@category Amazing} library my_library;
You can specify “macros”, i.e. reusable pieces of documentation. For that, first specify a template anywhere in the comments, like:
/// {@template template_name} /// Some shared docs /// {@endtemplate}
and then you can insert it via {@macro template_name}
, like
/// Some comment /// {@macro template_name} /// More comments
Template definitions are currently unscoped -- if dartdoc reads a file containing a template, it can be used in anything dartdoc is currently documenting. This can lead to inconsistent behavior between runs on different packages, especially if different command lines are used for dartdoc. It is recommended to use collision-resistant naming for any macros by including the package name and/or library it is defined in within the name.
If --auto-include-dependencies
flag is provided, dartdoc tries to automatically add all the used libraries, even from other packages, to the list of the documented libraries.
Please file reports on the GitHub Issue Tracker. Issues are labeled with priority based on how much impact to the ecosystem the issue addresses and the number of generated pages that show the anomaly (widespread vs. not widespread).
Some examples of likely triage priorities:
P0
P1
P2
P3
Please see the dartdoc license.
Generated docs include:
github.css
(c) Vasily Polovnyov vast@whiteants.net