jsduck 2.0.pre4 → 3.0.pre

data/.gitignore

@@ -2,4 +2,5 @@
 template/extjs
 template/resources/css
 template/resources/sass/.sass-cache
+template-min/
 sdk-vars.rb

data/README.md

@@ -63,66 +63,143 @@ Getting it
 ----------
 
 Standard rubygems install should do (use the `--pre` switch to get the
-latest 2.0 version which this README documents, otherwise you will get
+latest 3.0 version which this README documents, otherwise you will get
 the stable but quite old [0.6][v0.6] version):
 
     $ [sudo] gem install --pre jsduck
 
-For hacking fork it from github:
-
-    $ git clone git://github.com/senchalabs/jsduck.git
-    $ cd jsduck
-    $ rake --tasks
-
-JsDuck depends on [json][], [RDiscount][], and [parallel][]; plus
-[RSpec][] for tests.
-
 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.
 
-[v0.6]: https://github.com/senchalabs/jsduck/tree/v0.6
-[json]: http://flori.github.com/json/
-[RDiscount]: https://github.com/rtomayko/rdiscount
-[parallel]: https://github.com/grosser/parallel
-[RSpec]: http://rspec.info/
+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][].
 
+[v0.6]: https://github.com/senchalabs/jsduck/tree/v0.6
+[download page]: https://github.com/senchalabs/jsduck/downloads
 
 Usage
 -----
 
-Just call it from command line with output directory and a directory
-containing your JavaScript files:
+For the simplest test-run just pass in the src/ dir of Ext JS 4:
 
-    $ jsduck your/project/js --verbose --output your/docs
+    $ jsduck ext-4.0.2a/src --output your/docs
 
-The `--verbose` flag creates a lot of output, but at least you will
-see that something is happening.
+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.  Now it might look like
+nothing is happening... check out the `--verbose` flag.  For more
+command line options type `jsduck --help`.
 
+The latest ext-4.0.6 release will produce only few warnings, so use
+that if you can get it.
 
-## Generating Docs for ExtJS 4
+Finally, to get more similar result to the [official Ext JS 4
+documentation][official], copy over the doc-resources directory, which
+contains the images referenced by the documentation:
 
-For the simplest test-run just pass in the src/ dir of ExtJS 4.  But
-to get more similar result to the [official ExtJS 4
-documentation][official], you should pass in some extra options and
-copy over the doc-resources directory, which contains the images
-referenced by the documentation:
-
-    $ jsduck ext-4.0.2a/src --output your/docs --ignore-global --exclude Error
     $ cp -r ext-4.0.2a/docs/doc-resources your/docs/doc-resources
 
-The `--ignore-global` will avoid the creation of a `global` class.
-The `--exclude Error` will ignore references to the `Error` class,
-which would otherwise result in several warnings.
+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 ext-4.0.2a/src project1/js project2/js --output your/docs
 
-Still, running JSDuck with the current ext-4.0.2a release is expected
-to generate a lot of warnings.  These should be fixed in some later
-releases.
+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.
 
 [official]: http://docs.sencha.com/ext-js/4-0/
 
 
+Hacking it
+----------
+
+For hacking fork it from github:
+
+    $ git clone git://github.com/senchalabs/jsduck.git
+
+JsDuck depends on [json][], [RDiscount][], and [parallel][]; plus
+[RSpec][] for tests, [compass][] for compiling the stylesheets, and
+[Sencha SDK tools][sdk-tools] for combining JavaScript files.  Make
+sure you have these installed:
+
+    $ gem list
+
+First smoke test. Run the testsuite:
+
+    $ cd jsduck
+    $ rake
+
+If everything is green continue with some configuration.  Copy an
+ExtJS 4 download inside template/extjs directory (you might just
+create a symlink if you wish so):
+
+    $ cp -r path/to/ext-4.0.2a template/extjs
+
+Now create a file `sdk-vars.rb` inside the jsduck directory.  Use the
+following template:
+
+    # path to Ext JS 4 build
+    EXT_DIR='/path/to/ext-4.0.2a'
+    # where to output the docs
+    OUT_DIR='/path/to/ouput/dir'
+    # path to SDK (for developers at Sencha)
+    SDK_DIR='/path/to/SDK'
+
+These config options define the input and output directories for the
+ext4 rake task.  Leave out the SDK_DIR option if you are not a Sencha
+developer.  Now run the task:
+
+    $ rake ext4
+
+This will generate a development/debug version of the docs app into
+the output directory you specified in `sdk-vars.rb` file.  Open up the
+directory in your web browser and see if everything looks fine.  (This
+task only creates the class documentation, don't worry about guides,
+examples, etc being missing, and the index page of api docs blank).
+
+This rake task is most suitable when developing the JavaScript side of
+the app, as it only symlinks the files in template/ directory,
+allowing you to modify the files there and see the results by just
+refreshing the browser window (and not having to run the rake task
+again and again).
+
+To generate a stand-alone version of documentation (which you could
+upload to some server), add export parameter to the rake task:
+
+    $ rake ext4[export]
+
+This will combine and compress the javascript files using Sencha SDK
+Tools and does not create symlinks to the development directory.
+
+For developing the Ruby side, try to please the unit tests.
+
+If you are a Sencha developer, use the `sdk` and `touch` tasks instead
+to generate either extjs or touch docs from the corresponding branches
+in SDK repository.
+
+Happy hacking.
+
+[json]: http://flori.github.com/json/
+[RDiscount]: https://github.com/rtomayko/rdiscount
+[parallel]: https://github.com/grosser/parallel
+[RSpec]: http://rspec.info/
+[compass]: http://compass-style.org/
+[sdk-tools]: http://www.sencha.com/products/sdk-tools/
+
+
 Documenting your code with JSDuck
 ---------------------------------
 
@@ -159,6 +236,21 @@ reported bugs, submitted patches, and provided a lot of useful input.
 Changelog
 ---------
 
+* 3.0.pre - Completely new theme with tabs
+  * Tabs are back
+  * Separate front page
+  * Guides in separate section
+  * New Videos section
+  * New Examples section
+  * Inline examples
+  * Syntax for documenting object properties.
+  * Syntax for documenting default values.
+  * New Syntax for optional parameters.
+  * Syntax for required configs.
+  * Print view and support for Google AJAX crawling.
+  * No more --show-private-classes option, private classes now always shown.
+  * Lots and lots of other fixes...
+
 * 2.0.pre4 - Fixes for the previous pre-release.
   * Paging of search results.
   * Support opening classes in tree in new tabs in IE and Firefox.