Skip to content

Latest commit

 

History

History
135 lines (93 loc) · 4.42 KB

README.md

File metadata and controls

135 lines (93 loc) · 4.42 KB
Raw

JsDuck

API documentation generator for Ext JS 4.

       ,~~.
      (  6 )-_,
 (\___ )=='-'
  \ .   ) )
   \ `-' /    hjw
~'`~'`~'`~'`~

JsDuck aims to be a better documentation generator for Ext JS than the old ext-doc was. It is used by Sencha to generate the official Ext JS 4 documentation.

The highlights of JSDuck are Markdown support and keeping you DRY by inferring a lot of information from code. Read the Guide for full overview.

Getting it

Standard rubygems install should do (use the --pre switch to get the latest 3.0 version which this README documents, otherwise you will get the stable but quite old 0.6 version):

$ [sudo] gem install --pre jsduck

If you encounter errors during gem installation, you may need to install the header files for compiling extension modules for ruby 1.8. For Debian systems you'll need the ruby1.8-dev package. For Red Hat / CentOS / Fedora use the ruby-devel package.

For Windows users out there, you can download the binary version, which includes Ruby interpreter and all dependencies bundled in a single .exe file. Grab it from the download page.

Usage

For the simplest test-run just use the --builtin-classes option to automatically produce documentation for JavaScript builtin classes like Array, String and Object:

$ jsduck --builtin-classes --output your/docs

You can also use --verbose option to see what's actually happening.

To generate docs for Ext JS 4 add path to the corresponding src/ dir:

$ jsduck --builtin-classes --output your/docs  extjs-4.0.2a/src

Running JSDuck with the current ext-4.0.2a release is expected to generate a lot of warnings. Because of the bugs in doc-comments a global class will also get created. You can disable this by adding --ignore-global switch. If you are bothered by the excessive amount of warnings, use the --no-warnings switch. For full list of command line options type jsduck --help=full.

The latest ext-4.0.6 release will produce only few warnings, so use that if you can get it.

Finally, to get more similar result to the official Ext JS 4 documentation, copy over the doc-resources directory, which contains the images referenced by the documentation:

$ cp -r ext-4.0.2a/docs/doc-resources your/docs/doc-resources

Note that the resulting documentation will only contain the API documentation. Guides, videos and examples will not be present. These can be added using more command line options, but for now those aren't well documented as the ext-4.0.2a release doesn't contain the source files for these.

To generate docs for your own project, simply add as many other input directories as needed:

$ jsduck --builtin-classes ext-4.0.2a/src project1/js project2/js --output your/docs

Of course you don't have to include the whole Ext JS into your documentation, but if your project is built on top of it, it makes sense to do so - otherwise you won't be able to see which methods your classes inherit from Ext JS classes.

To create guides, videos and other sections, read about the Advanced Usage in wiki.

Hacking it

See Hacking guide in wiki.

Documenting your code

All the supported syntax is described in the Guide.

Copying

JsDuck is distributed under the terms of the GNU General Public License version 3.

JsDuck was developed by Rene Saarsoo, with many contributions from Nick Poulden.

Thanks to Ondřej Jirman, Thomas Aylott, johnnywengluu, gevik, ligaard, and many-many others who reported bugs, submitted patches, and provided a lot of useful input.

Changelog

See Changelog page in wiki.