JSDuckを利用してみる。
FaceBookで@martini3ozさんがシェアしててググったら@kotsutsumiさんがTwitterで
質問に答えてて、
結果、こちらにお世話になりました。
さて何からすればいいのか。という取っ掛かりの部分、
とても助かりました。ありがとうございました。
チュートリアルを実施してみたので ちょっと残しておきます。
目指すゴール
左にメニューがあって 内容が切り替わる。と、 で、内容は都度MarkDownで作成できて任意に増やせればOK。インストール
$ sudo gem install jsduck
ヘルプを見てみる。–helpで引いたら=fullつければ全て見れるってから全て見てみた。
$ jsduck --help=full 12-06-18
Usage: jsduck [options] files/dirs...
-o, --output=PATH Directory to output all this amazing documentation.
This option MUST be specified (unless --stdout).
Use dash '-' to write docs to STDOUT (only export).
--ignore-global Turns off the creation of global class.
--external=Foo,Bar,Baz Declares list of external classes. These classes
will then not generate warnings when used in type
definitions or inherited from.
--builtin-classes Includes docs for JavaScript builtin classes.
--meta-tags=PATH Path to Ruby file or directory with custom
meta-tag implementations.
--encoding=NAME Input encoding (defaults to UTF-8).
-v, --verbose This will fill up your console.
Customizing output:
--title=TEXT Custom title text for the documentation.
Defaults to 'Sencha Docs - Ext JS'
--footer=TEXT Custom footer text for the documentation.
Defaults to: 'Generated with JSDuck {VERSION}.'
--head-html=HTML HTML to append to the <head> section of index.html.
--body-html=HTML HTML to append to the <body> section index.html.
--welcome=PATH Path to HTML file with content for welcome page.
--guides=PATH Path to JSON file describing the guides. The file
should be in a dir containing the actual guides.
A guide is a dir containing README.md, icon.png,
and other images referenced by the README.md file.
--videos=PATH Path to JSON file describing the videos.
--examples=PATH Path JSON file describing the examples.
--categories=PATH Path to JSON file which defines categories for classes.
--no-source Turns off the output of source files.
--pretty-json Turn on pretty-printing of JSON.
--images=PATH Search path for including images referenced by
{@img} tag. Several paths can be specified by
using the option multiple times.
--link=TPL HTML template for replacing {@link}.
Possible placeholders:
%c - full class name (e.g. 'Ext.Panel')
%m - class member name prefixed with member type
(e.g. 'method-urlEncode')
%# - inserts '#' if member name present
%- - inserts '-' if member name present
%a - anchor text for link
Default is: '<a href="#!/api/%c%-%m" rel="%c%-%m" class="docClass">%a</a>'
--img=TPL HTML template for replacing {@img}.
Possible placeholders:
%u - URL from @img tag (e.g. 'some/path.png')
%a - alt text for image
Default is: '<p><img src="%u" alt="%a"></p>'
--export=TYPE Exports docs in JSON. TYPE is one of:
* full - full class docs.
* api - only class- and member names.
* examples - extracts inline examples from classes.
--seo Creates index.php that handles search engine traffic.
--eg-iframe=PATH An HTML file to use inside an iframe
to display inline examples.
--examples-base-url=URL Base URL for examples with relative URL-s.
--tests Creates page for testing inline examples.
--stats Creates page with all kinds of statistics. Experimental!
フォルダの配置を決めよう
作業用ディレクトリ作成~/UserDir/jsducktest
出力用ディレクトリ指定
~/UserDir/jsducktest/release
テンプレートとなるhtmlを作成してみよう
index.htmlを作成して、下記を記載。<h1>HELLO WORLD h1</h1>
<h2>HELLO WORLD h2</h2>
<h3>HELLO WORLD h3</h3>
<h4>HELLO WORLD h4</h4>
<h5>HELLO WORLD h5</h5>
<h6>HELLO WORLD h6</h6>
たったこれだけとしておく。
▾ jsducktest/
▸ release/
.DS_Store
index.html
※releaseはフォルダのみindex.htmlを作成してしてみる
ビルドしてみる。
- 早速ビルドです。
$jsduck -o ~/UserDir/jsducktest/release –welcome=~/UserDir/jsducktest/index.html
※パスはわざとフルパス指定にしてます。 ※作業用ディレクトリに移動してやると省略できてよいです。
できたらアクセス。
release配下のindex.htmlにブラウザからアクセスしてみます。こんな感じになりました。
 |
| index.html(welcomeページのみ) |
次に左のメニュー。
- 作業用ディレクトリに「guides」ディレクトリを作成
このディレクトリ配下のサブディレクトリごとにページを作るイメージです。 ですから、、、
このディレクトリ配下にREADME.md（これが本文になります）作ってあとでビルドして
リンクさせます。
ですので、subdir1,とsubdir2を作ってみました。 その中にREADME.mdを作っておきます。もちろんMarkDownで書いておきます。
現在の状況
▾ jsducktest/
▾ guides/
▾ subdir1/
icon-lg.png
README.md
sample.png
▾ subdir2/
README.md
▸ release/
.DS_Store
index.html
これはTreePanel用のオブジェクトリテラルを書いてあげるんですね。 作業用ディレクトリ直下にguides.jsonファイルを作って、、、下記のような内容で記載。
(guides.json)
[
{
"title": "RootNode",
"items": [{
"name": "subdir1",
"title": "サブディレクトリ1",
"description": "解説1"
},{
"name": "subdir2",
"title": "サブディレクトリ2",
"description": "解説2"
}]
}
]
ビルドしてみる(オプションを別ファイルにしてみる)
早速ビルドです。今度はヘルプにのっている様に、他のパラメタも。 たくさんのオプションが増えてきたので別ファイルで記述してみます。 json形式でオプションを設定して–configで設定します。(jsduck.jsonの内容：ファイル名は任意)
{
"--title": "jsducktest!!!",
"--guides": "guides.json",
"--welcome": "index.html"
"--footer": "footer!!!",
"--head-html": "head",
"--body-html": "body"
}
jsduck -o release --config=jsduck.json
できたらアクセス。
release配下のindex.htmlにブラウザからアクセスしてみます。こんな感じになりました。
色々と試してみました。
(jsduck.jsonファイル名は任意){
"--title": "jsducktest!!!",
"--guides": "guides.json",
"--videos":"videos.json",
"--categories":"categories.json",
"--welcome": "index.html",
"--footer": "footer!!!",
"--head-html":"head",
"--body-html":"body",
"--warnings": ["-link", "-no_doc"],
"--":[
"src/Hoge/AbstructSample.js",
"src/sample.js"
]
}
jsduck -o release --config=jsduck.json
▾ jsducktest/
▾ categories/
▸ subdir1/
▸ subdir2/
▾ guides/
▸ subdir1/
▸ subdir2/
▾ release/
▸ extjs/
▸ guides/
▸ output/
▸ resources/
▸ source/
app.js
data.js
eg-iframe.html
favicon.ico
index.html
▾ src/
▸ Hoge/
sample.js
▾ videos/
▸ subdir1/
▸ subdir2/
.DS_Store
categories.json
guides.json
index.html
jsduck.json
videos.json
できたらアクセス。
release配下のindex.htmlにブラウザからアクセスしてみます。
Gitにのっけました。
release配下のindex.htmlで上の出来上がりが確認できるかと思います。https://github.com/froggugugugu/jsducktest
ビデオを見てみる
紹介されているように、ビデオを見てみます。http://vimeo.com/33465319
４分１７秒あたりから上記のカスタムパラメタとリンクする各メニュータブの説明
６分２７秒あたりからソース内のマークダウン記法について あーそうなんだ。コメントもマークダウンでかけばいいのね。で{@link}とかなわけだ。
インストールについて
１６分５６秒あたりからインストールです。タイトルについて
１８分４２秒あたりからタイトルの変更。１９分あたりからコメントブロック入れようね。
２０分あたりからソース内のパラメータに沿ったDocumentの吐き出され方 alternateClassNameとかsingletonとか。 設定するとアイコンが変わったり、とか、こう出るよ。的な。
２１分でコメントブロックの記載について。 Ext.define直前のドキュメントコメントはクラス説明文にあたるみたい。
propertyについて
２１分５０秒付近でのプロパティ直前のドキュメントコメントについては/**
* @property {[型]} [名前] [説明]
*/
configオプションについて
２２分４０秒付近ではコンフィグオプションの説明config:{
/**
* @cfg
* [説明]
*/
hogehoge: 0.5
}
functionについて
２３分３７秒付近ではfunctionの説明 functionの直前のコメントブロックに/**
* [説明]
* @return {[型]} 説明
*/
functionについて（戻り値Object）
２５分０７秒付近ではfunctionの説明(Object戻り)/**
* [説明]
* @return {Object}
* @return {[型]} return.[Objectのメンバ名] 説明
* @return {[型]} return.[Objectのメンバ名] 説明
* ...
*/
functionについて（alias）
２６分３０秒付近ではfunctionの説明(alias)/**
* @alias クラス名#メソッド名
*/
/**
* @alias [クラス名#メソッド名]
* @duprecated [説明] {@link}
*/
eventについて
２９分２０秒付近ではeventの説明/**
* @event [イベント名]
* [説明]
* @param {[型]} [説明]
*/
/**
* @event [イベント名] [説明]
*/
privateクラスについて
３１分００秒付近ではprivateクラスの説明 Ext.define直前のドキュメントコメントで/**
* @private
*/
exampleコードの機能について
３１分３６秒付近では例の説明 Ext.define直前のドキュメントコメントで/**
* @example
* [code....]
*/
コードブロックとなるわけですが、プレビュー機能等をつけるときは
この@exampleをつけます。
この際、eg-iframe.htmlを利用するので
配下にあるeg-iframe.htmlに当該jsファイルを読み込む設定を
しておきます。
ビルドするときはパラメタに–eg-iframe=[eg-iframe.htmlのパス]を設定します。
imageについて
３４分００秒付近からイメージの説明 Ext.define直前のドキュメントコメントで {@img [ファイル名]} としておきます。 この際、ビルドするときはパラメタに–images=[画像が入ったフォルダパス]を設定します。categoriesの設定について
３６分００秒付近からイメージの説明 作業用ディレクトリ直下にcategories.jsonファイルを作って、、、下記のような内容で記載。[
{
"name": "Jsducktest.js",
"groups": [
{
"name": "subdir1",
"classes": [
"class1_1",
"class1_2"
]
},
{
"name": "subdir2",
"classes": [
"class2_1",
"class2_2"
]
}
]
}
]
guidesの設定について
３９分２０秒付近からguidesの説明 作業用ディレクトリ直下にguides.jsonファイルを作って、、、下記のような内容で記載。[
{
"title": "RootNode",
"items": [
{
"name": "subdir1",
"title": "サブディレクトリ1",
"description": "解説1"
},
{
"name": "subdir2",
"title": "サブディレクトリ2",
"description": "解説2"
}
]
}
]
https://github.com/senchalabs/jsduck/blob/master/lib/jsduck/guides.rb
この際、ビルドするときはパラメタに–guides=guides.jsonを設定します。
welcomeの設定について
４２分２２秒付近からwelcomeページの設定について 作業用ディレクトリ直下にwelcome.htmlファイルを作って、、、この際、ビルドするときはパラメタに--welcome=welcome.htmlを設定します。
videosの設定について
４３分１８秒付近からvideosの設定について 作業用ディレクトリ直下にvideos.jsonファイルを作って、、、下記のような内容で記載。[
{
"title": "RootNode",
"items": [
{
"id": "9071202",
"title": "サブディレクトリ1",
"description": "解説1",
"thumb": "http://b.vimeocdn.com/ts/439/819/439819_200.jpg"
}
]
}
]
examlesの設定について
４４分４０秒付近からexamplesの設定について 作業用ディレクトリ直下にexamples.jsonファイルを作って、、、下記のような内容で記載。[
{
"title": "RootNode",
"items": [
{
"text": "例",
"url": "[index.html]",
"icon": "[icon]",
"desc": "解説1"
}
]
}
]
なんだよ、、まぁ、ここまで見てアレですが、
４７分２０秒付近からhttps://github.com/senchalabs/jsduck/wiki/Guide
https://github.com/senchalabs/jsduck/wiki/Advanced-Usage
に今までの解説がありました。。。。
0 件のコメント:
コメントを投稿