yuidoc-asp

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Using YUIDoc</title> <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Maven+Pro:400,700"> <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.1/build/cssgrids/grids-min.css"> <link rel="stylesheet" href="../assets/css/main.css"> <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css"> <link rel="icon" href="../assets/favicon.ico"> <script src="http://yui.yahooapis.com/3.5.1/build/yui/yui.js"></script> </head> <body> <a href="https://github.com/yui/yuidoc"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a> <div id="doc"> <div id="hd"> <h1><img src="http://yuilibrary.com/img/yui-logo-2x.png" width="117" height="52">Using YUIDoc</h1> </div> <div class="crumbs"> <a href="../">Main Page</a> <a name="Arrow">></a> <a href="../args/index.html">Using YUIDoc</a> </div> <a href="#toc" class="jump">Jump to Table of Contents</a> <div class="yui3-g"> <div class="yui3-u-3-4"> <div id="main"> <div class="content"><p>Generating documentation with YUIDoc is as simple as going to the top of your source tree and running:</p> <pre class="code terminal"><span class="noselect">$ </span>yuidoc .</pre> <p>However, you can configure YUIDoc's behavior further by providing <a href="#command-line">command line options</a>, a <a href="#json">JSON configuration file</a>, or even both. This section discusses the <code>yuidoc</code> command line tool in more detail.</p> <h2 id="command-line">Running YUIDoc on the Command Line</h2> <p>Certain <code>yuidoc</code> command line options correspond to entries in the the <a href="#json"><code>yuidoc.json</code> configuration file</a>. Command line options always take priority.</p> <pre class="code terminal">YUI Doc generates API documentation from a modified JavaDoc syntax. Current version (0.6.0) Usage: yuidoc <options> <input path> Common Options: -c, --config, --configfile <filename> A JSON config file to provide configuration data. You can also create a yuidoc.json file and place it anywhere under your source tree and YUI Doc will find it and use it. -e, --extension <comma sep list of file extensions> The list of file extensions to parse for api documentation. (defaults to .js) -x, --exclude <comma sep list of directories> Directories to exclude from parsing (defaults to '.DS_Store,.svn,CVS,.git,build_rollup_tmp,build_tmp') -v, --version Show the current YUIDoc version --project-version Set the doc version for the template -N, --no-color Turn off terminal colors (for automation) -C, --no-code Turn off code generation (don't include source files in output) -n, --norecurse Do not recurse directories (default is to recurse) --no-sort Do not alphabetical sorting of attributes, events, methods, and properties -S, --selleck Look for Selleck component data and attach to API meta data -V, --view Dump the Handlebars.js view data instead of writing template files -p, --parse-only Only parse the API docs and create the JSON data, do not render templates -o, --outdir <directory path> Path to put the generated files (defaults to ./out) -t, --themedir <directory path> Path to a custom theme directory containing Handlebars templates -H, --helpers <comma separated list of paths to files> Require these file and add Handlebars helpers. See docs for more information --charset CHARSET Use this as the default charset for all file operations. Defaults to 'utf8' -h, --help Show this help -q, --quiet Supress logging output -T, --theme <simple|default> Choose one of the built in themes (default is default) --syntaxtype <js|coffee> Choose comment syntax type (default is js) --server <port> Fire up the YUIDoc server for faster API doc developement. Pass optional port to listen on. (default is 3000) --lint Lint your docs, will print parser warnings and exit code 1 if there are any <input path> Supply a list of paths (shell globbing is handy here)</pre> <h3 id="server">Running YUIDoc in Server Mode</h3> <p> Most documentation tools (including YUIDoc) involve some sort of build process. However, YUIDoc provides a unique feature that allows you to short-circuit this. </p> <p> In <dfn>server mode</dfn>, YUIDoc fires up a small Node.js based server and begins parsing and displaying documentation in real time. This greatly speeds up the documentation authoring process, as you can edit your source code and preview changes with a simple browser reload, rather than waiting for a build. </p> <p>To activate server mode on <code>localhost:3000</code>, run <code>yuidoc --server</code>. You can optionally specify an alternate port:</p> <pre class="code terminal">yuidoc --server or yuidoc --server 5000</pre> Then visit: <pre class="code terminal">http://127.0.0.1:3000/ or http://127.0.0.1:5000/</pre> <p> Any changes you make to your YUIDoc comment blocks. will be reflected when you reload the browser. It's that simple! </p> <p><strong>NOTE:</strong> Server mode is not a replacement for building and hosting your documentation, just a handy previewing tool. For production, you should generate static HTML pages and host them on a real web server.</p> <h3 id="working-with-yuidoc-parsed-data">Working with YUIDoc Parsed Data</h3> <p> YUIDoc generates a <code>data.json</code> file after it parses your API documentation. The <code>external.data</code> config option enables you to import a YUIDoc <code>data.json</code> file from another project and mix it into your own documentation. </p> <p> This feature is handy when you are extending another project and would like to link back to their API documentation. For example, importing YUI Library's <code>data.json</code> file would enable YUIDoc to automatically link back to <code>Base</code>, <code>EventTarget</code>, and other core YUI objects that your own API might be extending or mixing in. </p> <p> Currently, importing external data enables YUIDoc to resolve HTML links <code>@extends</code> or <code>@use</code> keywords, but does <em>not</em> cause YUIDoc to generate complete documentation for the external API. Future versions of YUIDoc may provide the option to mix in the data natively and reproduce the external API right along with your own. </p> <h4 id="external-data">Adding External YUIDoc Data to Your Project</h4> <p> Create an <code>external</code> object under the <code>options</code> object in your <code>yuidoc.json</code> file and give it a property called <code>data</code> pointing to the URL of the external <code>data.json</code> file you wish to import. <code>data</code> can be a string or an array of strings. </p> <pre class="code prettyprint">{ "options": { "external": { "data": "http://yuilibrary.com/yui/docs/api/data.json" } } }</pre> <p> Also, you are able to give <code>base</code> data within <code>external</code> for external base URLs. </p> <pre class="code prettyprint">{ "options": { "external": { "data": [ { "base": "http://emberjs.com/api/", "json": "http://builds.emberjs.com/tags/v1.5.1/ember-docs.json" }, { "base": "http://emberjs.com/api/", "json": "http://builds.emberjs.com/tags/v1.0.0-beta.6/ember-data-docs.json" } ] } } }</pre> <p> <strong>NOTE:</strong> YUIDoc currently fetches external data on each run with no caching. </p> <h2 id="json">Configuring YUIDoc with yuidoc.json</h2> <p> You can also store most YUIDoc configurables in a <code>yuidoc.json</code> file. As mentioned in the <a href="#command-line">command line arguments</a> section, command line options always take priority over <code>yuidoc.json</code> configuration values.</p> </p> <p> The <code>yuidoc.json</code> file must reside in a directory somewhere under where you execute <code>yuidoc</code>. YUIDoc will scan the tree for this file before doing anything else. </p> <p>A short example <code>yuidoc.json</code> file would resemble:</p> <pre class="code prettyprint">{ "name": "The Foo API", "description": "The Foo API: a library for doing X, Y, and Z", "version": "1.2.1", "url": "http://example.com/", "options": { "outdir": "../build/apidocs" } }</pre> See below for <a href="#ex-yui3">more</a> <a href="#ex-yuidoc">examples</a>. <h3 id="yuidocjson-fields">yuidoc.json Fields</h3> <h4 id="general-yuidoc-project-information">General YUIDoc Project Information</h4> <table> <tr> <th>Name</th> <th>Description</th> </tr> <tr> <td><code>name</code></th> <td>A short name for the project.</td> </tr> <tr> <td><code>description</code></th> <td>A one or two sentence description of the project.</td> </tr> <tr> <td><code>version</code></th> <td>The project's current version, as some kind of meaningful string.</td> </tr> <tr> <td><code>url</code></th> <td>The project's primary URL. This does not necessarily have to be the URL of the generated API documentation.</td> </tr> <tr> <td><code>logo</code></th> <td> The logo to add to the header of all generated HTML documentation. If you do not provide a header, YUIDoc will use the YUI logo by default. </td> </tr> </table> <h4 id="yuidoc-options">YUIDoc Options</h4> <p>Within the <code>options</code> object, you can provide any of the following fields:</p> <table> <tr> <th>Name</th> <th>Description</th> </tr> <tr> <td><code>linkNatives</code></th> <td>Selects whether to autolink native types such as <code>String</code> and <code>Object</code> over to the Mozilla Developer Network. </td> </tr> <tr> <td><code>attributesEmit</code></th> <td> Selects whether YUIDoc should autogenerate documentation for change events generated by the <a href="http://yuilibrary.com/yui/docs/api/classes/Attribute.html">YUI Attribute API</a>. When a YUI attribute <code>foo</code> changes its value, YUI automatically fires a custom event named <code>fooChange</code>. Setting <code>attributesEmit</code> to <code>true</code> instructs YUIDoc to automatically generate documentation for each of these events. You can set this value to <code>false</code> if you think that your audience is well aware of change events and would not benefit from this extra verbiage. </td> </tr> <tr> <td><code>selleck</code></th> <td> Selects whether to add <a href="http://rgrove.github.com/selleck/">Selleck</a> metadata. If <code>true</code>, YUIDoc searches for a <code>component.json</code> file above the source tree and attaches that data to the module data as extra information. </td> </tr> <tr> <td><code>ignorePaths</code></th> <td>Specifies an array of string paths to ignore when using shell globbing. This only removes top level items from the list to initally scan. Use <code>exclude</code> to remove specific directories.</td> </tr> <tr> <td><code>exclude</code></th> <td>Specify a comma separated list of names you want to exclude from parses when YUIDoc recurses the source tree.</td> </tr> <tr> <td><code>paths</code></th> <td> Specifies a single string <code>glob</code> or array of globs to use when searching the source tree for docs to parse. </td> </tr> <tr> <td><code>outdir</code></th> <td>Specifies the directory in which to place the rendered HTML files and assets.</td> </tr> <tr> <td><code>tabtospace</code></th> <td>Specifies the number of spaces each tab character in source code should be converted to when using YUIDoc's source code view. The default is 8.</td> </tr> <tr> <td><code>external.data</code></th> <td> Provides a link to an external <code>data.json</code> file to merge into the local api docs. For more information, refer to the <a href="#external-data">external data example</a>. </td> </tr> <tr> <td><code>markdown</code></td> <td> Options to pass to markdown-it, the Markdown compiler used to compile API descriptions. See the <a href="https://markdown-it.github.io/markdown-it/#MarkdownIt.new">markdown-it API</a> for details. </td> </tr> </table> <h3 id="ex-yui3">Example: YUI 3 Library API </h3> <p> This sample <code>yuidoc.json</code> file is used in the <a href="http://yuilibrary.com/">YUI 3</a> project: </p> <pre class="code prettyprint">{ "name": "YUI 3", "description": "YUI 3 JavaScript Framework", "version": "3.5.0", "url": "http://yuilibrary.com/", "options": { "linkNatives": "true", "attributesEmit": "true", "selleck": "true", "ignorePaths": [ "simpleyui" ], "paths": "*/js", "outdir": "../api-js" } }</pre> <h3 id="ex-yuidoc">Example: YUIDoc API</h3> <p>This sample <code>yuidoc.json</code> file is used in the YUIDoc project itself:</p> <pre class="code prettyprint">{ "name": "YUIDoc", "description": "YUIDoc documentation tool written in JavaScript", "version": "0.2.38", "url": "http://yuilibrary.com/projects/yuidoc", "logo": "http://yuilibrary.com/img/yui-logo.png", "options": { "external": { "data": "http://yuilibrary.com/yui/docs/api/data.json" }, "linkNatives": "true", "attributesEmit": "true", "paths": [ "./lib" ], "outdir": "./output/api" } }</pre> </div> </div> </div> <div class="yui3-u-1-4"> <div class="sidebar"> <ul class="links"> <li><a href="https://github.com/yui/yuidoc/" class="button">Get the Source</a></li> <li><a href="https://groups.google.com/forum/#!forum/yuidoc" class="button">Questions? Join the Mailing List</a></li> <li><a href="https://github.com/yui/yuidoc/issues/" class="button">File an Issue</a></li> <li><a href="../api/" class="button">View API Documentation</a></li> </ul> <div class="sidebox"> <div class="hd"> <h2 class="no-toc">Build Status</h2> </div> <div class="bd"> <a href="http://travis-ci.org/yui/yuidoc"><img src="https://secure.travis-ci.org/yui/yuidoc.png?branch=master" border="0"></a> </div> </div> <div id="toc" class="sidebox"> <div class="hd"> <h2 class="no-toc">Table of Contents</h2> </div> <div class="bd"> <ul class="toc"> <li> <a href="#command-line">Running YUIDoc on the Command Line</a> <ul class="toc"> <li> <a href="#server">Running YUIDoc in Server Mode</a> </li> <li> <a href="#working-with-yuidoc-parsed-data">Working with YUIDoc Parsed Data</a> <ul class="toc"> <li> <a href="#external-data">Adding External YUIDoc Data to Your Project</a> </li> </ul> </li> </ul> </li> <li> <a href="#json">Configuring YUIDoc with yuidoc.json</a> <ul class="toc"> <li> <a href="#yuidocjson-fields">yuidoc.json Fields</a> <ul class="toc"> <li> <a href="#general-yuidoc-project-information">General YUIDoc Project Information</a> </li> <li> <a href="#yuidoc-options">YUIDoc Options</a> </li> </ul> </li> <li> <a href="#ex-yui3">Example: YUI 3 Library API </a> </li> <li> <a href="#ex-yuidoc">Example: YUIDoc API</a> </li> </ul> </li> </ul> </div> </div> </div> </div> </div> </div> <script src="../assets/vendor/prettify/prettify-min.js"></script> <script>prettyPrint();</script> </body> </html>