dart-sdk/utils/dartdoc
rnystrom@google.com 7e2ea12a4c Add a mode to dartdoc to generate the navigation on the client.
Right now, the generated docs are pretty huge (100MB for all of the main libs). This is mainly
because each generated HTML page includes full navigation for each type in the containing
library. For stuff like dart:html, that's tons of HTML. Even after compression, the docs are
9.2MB. Also, they take a long time to generate (30s on my laptop).

This patch adds a mode you can use called "live-nav" (and makes it the default). With that
mode, pages do not include navigation. Instead, we generate a single nav.json file with the
navigation data. Client-side Dart code does an XHR for that and then renders the navigation
on the fly.

This gets the generated docs down to 13.3MB (2MB after compression) and gets doc generation
up to 6.3s for everything.

The two downsides are:

1. There's a visible flash on page load when it renders the nav since it's asynchronous.
2. You can't browse docs locally just using file://. To be able to XHR the nav.json, you
   either need to enable file access in your browser or run a local server.

Review URL: https://chromiumcodereview.appspot.com//9256002

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@3445 260f80e4-7a28-3924-810f-c04153c831b5
2012-01-19 20:10:51 +00:00
..
static Hook up favicon, link to main page, and fix process bug. 2011-12-21 23:35:24 +00:00
.gitignore Add a mode to dartdoc to generate the navigation on the client. 2012-01-19 20:10:51 +00:00
ast.dart Move markdown library. 2011-12-20 01:36:07 +00:00
block_parser.dart Move markdown library. 2011-12-20 01:36:07 +00:00
classify.dart Add a mode to dartdoc to generate the navigation on the client. 2012-01-19 20:10:51 +00:00
client-live-nav.dart Add a mode to dartdoc to generate the navigation on the client. 2012-01-19 20:10:51 +00:00
client-shared.dart Add a mode to dartdoc to generate the navigation on the client. 2012-01-19 20:10:51 +00:00
client-static.dart Add a mode to dartdoc to generate the navigation on the client. 2012-01-19 20:10:51 +00:00
comment_map.dart Refactor dartdoc into a class. Use method overriding to extend. 2011-12-15 21:24:18 +00:00
dartdoc Add a mode to dartdoc to generate the navigation on the client. 2012-01-19 20:10:51 +00:00
dartdoc.dart Add a mode to dartdoc to generate the navigation on the client. 2012-01-19 20:10:51 +00:00
files.dart Add the ability to link to members and constructors of other classes in Dartdoc. 2012-01-12 00:21:27 +00:00
html_renderer.dart Hook up the dartdoc tests to test.py, test.dart, and frog/presubmit.py. 2012-01-11 21:29:13 +00:00
htmldoc Add a script to generate HTML and DOM docs with cross-links to one another. 2011-12-07 22:15:12 +00:00
inline_parser.dart Move markdown library. 2011-12-20 01:36:07 +00:00
markdown.dart Move markdown library. 2011-12-20 01:36:07 +00:00
README.txt Fix typo in dartdoc README. 2011-12-22 19:51:58 +00:00
utils.dart Add a script to generate HTML and DOM docs with cross-links to one another. 2011-12-07 22:15:12 +00:00

Dartdoc generates static HTML documentation from Dart code.

To use it, from this directory, run:

    $ dartdoc <path to .dart file>

This will create a "docs" directory with the docs for your libraries.


How docs are generated
----------------------

To make beautiful docs from your library, dartdoc parses it and every library it
imports (recursively). From each library, it parses all classes and members,
finds the associated doc comments and builds crosslinked docs from them.

"Doc comments" can be in one of a few forms:

    /**
     * JavaDoc style block comments.
     */

    /** Which can also be single line. */

    /// Triple-slash line comments.
    /// Which can be multiple lines.

The body of a doc comment will be parsed as markdown which means you can apply
most of the formatting and structuring you want while still having docs that
look nice in plain text. For example:

    /// This is a doc comment. This is the first paragraph in the comment. It
    /// can span multiple lines.
    ///
    /// A blank line starts a new paragraph like this one.
    ///
    /// *   Unordered lists start with `*` or `-` or `+`.
    /// *   And can have multiple items.
    ///     1. You can nest lists.
    ///     2. Like this numbered one.
    ///
    /// ---
    ///
    /// Three dashes, underscores, or tildes on a line by themselves create a
    /// horizontal rule.
    ///
    ///     to.get(a.block + of.code) {
    ///       indent(it, 4.spaces);
    ///       like(this);
    ///     }
    ///
    /// There are a few inline styles you can apply: *emphasis*, **strong**,
    /// and `inline code`. You can also use underscores for _emphasis_ and
    /// __strong__.
    ///
    /// An H1 header using equals on the next line
    /// ==========================================
    ///
    /// And an H2 in that style using hyphens
    /// -------------------------------------
    ///
    /// # Or an H1 - H6 using leading hashes
    /// ## H2
    /// ### H3
    /// #### H4 you can also have hashes at then end: ###
    /// ##### H5
    /// ###### H6

There is also an extension to markdown specific to dartdoc: A name inside
square brackets that is not a markdown link (i.e. doesn't have square brackets
or parentheses following it) like:

    Calls [someMethod], passing in [arg].

is understood to be the name of some member or type that's in the scope of the
member where that comment appears. Dartdoc will automatically figure out what
the name refers to and generate an approriate link to that member or type.


Attribution
-----------

dartdoc uses the delightful Silk icon set by Mark James.
http://www.famfamfam.com/lab/icons/silk/