Skip to content

Latest commit

 

History

History
145 lines (101 loc) · 6.39 KB

README.md

File metadata and controls

145 lines (101 loc) · 6.39 KB
Raw

CKEditor JSDuck Gem

This repository is used for storing CKEditor modifications for JSDuck, API documentation framework that is used for the CKEditor 4 developer documentation.

Repository

  1. The master branch always refers to the official JSDuck master branch. It's a development branch.
  2. The stable branch contains the latest stable official JSDuck release plus CKEditor's modifications. Gem packages should be built from this branch.
  3. The ckeditor-customizations branch contains all modifications made by the CKEditor team and can be used while updating JSDuck to reapply those changes.

Building the CKEditor JSDuck Gem

More detailed guide can be found in the JSDuck wiki.

The most suitable version is ruby 1.9.3. You may use RVM for your convenience.

  1. Install Sencha SDK Tools for your OS.
  2. > sudo gem install rake rspec json rdiscount parallel dimensions rkelly-remix
  3. Install sass gem:
    • > sudo gem install sass -v 3.1.18 (for ruby version >= 2)
    • > sudo gem install sass -v 3.1.1 (for ruby version < 2)
  4. > sudo gem install compass -v 0.12.2
  5. > git clone git@github.com:ckeditor/jsduck.git
  6. > cd jsduck
  7. > git co stable
  8. > rake configure
  9. > rake ext4 (it gives a lot of warnings when executed for the first time — you can repeat it)
  10. To generate the gem you first need to have a JSDuck-built documentation application available at http://localhost/docs/. The jsduck/output directory should be available under http://localhost/docs/ so the easiest way is to run from localhost's root:

> ln -s path/to/jsduck/output docs

  1. > rake bump["0.0.2"] (update version number if you made any changes)
  2. > rake gem
  3. If you want to commit a new version, remove the old gem and add a new one to the repository.

Building the CKEditor Documentation

Read the instructions in the ckeditor-docs repository.

Modifying JSDuck

  1. Rebuilding the gem package:
  2. If you modified JSDuck version (merged upstream's master), make sure to run all rake tasks starting from rake configure in step 8 above.
  3. If you only modified JSDuck code within a previously built version, it's enough to build the gem package, unless templates have been modified.
  4. Committing changes:
  5. All code modifications should be done in the ckeditor-customizations branch, so that they would be easily reapplicable in the future.
  6. After making any changes, first commit code changes (this may be more than one commit), then bump the JSDuck version, build a new gem package, remove the old one from the repository and add the new one, then commit the rebuilt package.
  7. Testing:

For testing purposes you can use the script available in bin/ckeditor-jsduck instead of constantly installing the rebuilt gem package. You need to temporarily modify the gruntfile.js script from the CKEditor documentation repository to use this file. The cmd should point to full path with bin/ckeditor-jsduck instead of ckeditor-jsduck.

If you modified JSDuck templates, then you need to run rake tasks up to rake gem (excluding bumping up the version of course), otherwise bin/ckeditor-jsduck will still be using old minified templates.

Customizations

List of applied customizations:

0.0.9

  1. Fix possible XSS in template index.php file. Reported by Bruno da Silva aka ipsbruno.

0.0.8

  1. Updated parallel gem dependency to 1.12.0 version.

0.0.7

  1. HTTPS support.

0.0.6

  1. Fixed ToC injection when <h1> is not the first element of a guide (it may be preceded by a license comment).

0.0.5

  1. Added support for the expanded property of guides menu items.
  2. Implemented multi-level TOC in guides.

0.0.4

  1. Made sidebar wider.

0.0.3

  1. Fixed canonical URL for documentation loaded from CDN.

0.0.2

  1. Introduced --head-html-common config option which makes it possible to extend the <head> of all templates.

0.0.1

  1. Gem name changed to ckeditor-jsduck to avoid conflicts.
  2. Event arguments are automatically wrapped with the eventInfo object.
  3. Developer's Guide table of contents tree is kept collapsed by default.
  4. Improved SEO by including meta tags in the Developer's Guide. They are configurable through the guides.json file.
  5. Added these instructions.

=================================================================================== CKEditor documentation uses JSDuck, API documentation generator for Sencha JavaScript frameworks.

JSDuck

Copying

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

JSDuck was developed by Rene Saarsoo, with contributions from Nick Poulden, Ondřej Jirman, Thomas Aylott, Dave Thompson, Ed Spencer, Rob Dougan, Scott Whittaker, Timo Tijhof, Brian Moeskau, Garry Yao, Yasin Okumus, Nicholas Boll and Katherine Chu.

Many thanks goes also to those who have most eagerly reported bugs: Ryan Nauman, Raphael Franchet, atian25, burnnat, Raphael Pigulla, Dmitry Bakaleinik, Alan Lindsay, Corey Butler, Nickolay Platonov, Matt Greer, Richard and Dmitry Pashkevich.

There are lots of others I haven't named here, who have provided their input.

JSDuck Changelog

See the Releases page.