From eb968fa737e91bfd40beabb5b4d56e7748e5f523 Mon Sep 17 00:00:00 2001 From: Gunther Brunner Date: Thu, 28 Aug 2014 21:04:32 +0900 Subject: [PATCH] Add Documentation in Markdown plus express middleware for in-site rendering. --- lib/units/app/index.js | 6 + res/app/app.js | 1 + res/app/docs/docs-controller.js | 19 +++ res/app/docs/docs.css | 52 +++++++++ res/app/docs/index.js | 14 +++ res/app/settings/language/index.js | 1 + res/app/settings/language/language-service.js | 2 + res/app/views/docs.jade | 16 +++ res/docs/en/index.md | 18 +++ res/docs/en/remote-debug.md | 94 +++++++++++++++ res/docs/ja/index.md | 4 + res/docs/ja/remote-shell.md | 110 ++++++++++++++++++ webpack.config.js | 24 ++-- 13 files changed, 349 insertions(+), 12 deletions(-) create mode 100644 res/app/docs/docs-controller.js create mode 100644 res/app/docs/docs.css create mode 100644 res/app/docs/index.js create mode 100644 res/app/views/docs.jade create mode 100644 res/docs/en/index.md create mode 100644 res/docs/en/remote-debug.md create mode 100644 res/docs/ja/index.md create mode 100644 res/docs/ja/remote-shell.md diff --git a/lib/units/app/index.js b/lib/units/app/index.js index d2ce2292..e5d3cd29 100644 --- a/lib/units/app/index.js +++ b/lib/units/app/index.js @@ -22,6 +22,7 @@ var browserIconMiddleware = require('./middleware/browser-icons') var appstoreIconMiddleware = require('./middleware/appstore-icons') var webpackServerConfig = require('./../../../webpack.config').webpackServer +var markdownServe = require('markdown-serve') module.exports = function(options) { var log = logger.createLogger('app') @@ -33,6 +34,11 @@ module.exports = function(options) { log.error('Proxy had an error', err.stack) }) + app.use('/static/docs', markdownServe.middleware({ + rootDirectory: pathutil.resource('docs') + , view: 'docs' + })) + app.set('view engine', 'jade') app.set('views', pathutil.resource('app/views')) app.set('strict routing', true) diff --git a/res/app/app.js b/res/app/app.js index 48d72230..21029ed1 100644 --- a/res/app/app.js +++ b/res/app/app.js @@ -15,6 +15,7 @@ require.ensure([], function (require) { require('./menu').name, require('./settings').name, require('./help').name, + require('./docs').name, require('./../common/lang').name ]) .config(function ($routeProvider, $locationProvider) { diff --git a/res/app/docs/docs-controller.js b/res/app/docs/docs-controller.js new file mode 100644 index 00000000..c78bc8b3 --- /dev/null +++ b/res/app/docs/docs-controller.js @@ -0,0 +1,19 @@ +module.exports = function DocsCtrl($rootScope, $scope, $window, $location) { + + $scope.goBack = function () { + $window.history.back() + } + + $scope.goHome = function () { + $location.path('/docs/en/index') + } + + $rootScope.$on("$routeChangeError", + function (event, current, previous, rejection) { + console.log("ROUTE CHANGE ERROR: " + rejection) + console.log('event', event) + console.log('current', current) + console.log('previous', previous) + + }) +} diff --git a/res/app/docs/docs.css b/res/app/docs/docs.css new file mode 100644 index 00000000..c47f4e76 --- /dev/null +++ b/res/app/docs/docs.css @@ -0,0 +1,52 @@ +.stf-docs h1 { + /*background: green;*/ +} + +.stf-docs .widget-container { + padding: 10px; +} + +.stf-docs h1 { + font-size: 32px; + color: #157afb; +} + +.stf-docs h1 { + margin-top: 10px; +} + +.stf-docs h2, +.stf-docs h3 { + margin-top: 40px; +} + +.stf-docs p, +.stf-docs li, +.stf-docs a { + font-size: 15px; +} + +.stf-docs h1:after, +.stf-docs h2:after, +.stf-docs h3:after { + content: ' '; + display: block; + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-top: 1px solid #eee; +} + +.stf-docs-navigation { + text-align: center; +} + +.stf-docs .docs-back { + position: absolute; + left: 10px; + border: 1px solid transparent; +} + +.stf-docs .docs-home { + border: 1px solid transparent; +} diff --git a/res/app/docs/index.js b/res/app/docs/index.js new file mode 100644 index 00000000..4406ed57 --- /dev/null +++ b/res/app/docs/index.js @@ -0,0 +1,14 @@ +require('./docs.css') + +module.exports = angular.module('stf.help.docs', []) + .config(['$routeProvider', function ($routeProvider) { + + $routeProvider.when('/docs/:lang/:document*', { + templateUrl: function (params) { + var document = params.document.replace('.md', '') + return '/static/docs/' + params.lang + '/' + document + } + }) + + }]) + .controller('DocsCtrl', require('./docs-controller')) diff --git a/res/app/settings/language/index.js b/res/app/settings/language/index.js index 313594a6..dc575e02 100644 --- a/res/app/settings/language/index.js +++ b/res/app/settings/language/index.js @@ -9,3 +9,4 @@ module.exports = angular.module('stf-ui-language', [ }]) .factory('LanguageService', require('./language-service')) .controller('LanguageCtrl', require('./language-controller')) + //.provider('language', require('./language-service')) diff --git a/res/app/settings/language/language-service.js b/res/app/settings/language/language-service.js index 27587097..510ea25f 100644 --- a/res/app/settings/language/language-service.js +++ b/res/app/settings/language/language-service.js @@ -4,6 +4,8 @@ module.exports = function LanguageServiceFactory( SettingsService , gettextCatalog ) { + // TODO: make this LanguageProvider so it can be used on config + var LanguageService = {} function detectLanguage() { diff --git a/res/app/views/docs.jade b/res/app/views/docs.jade new file mode 100644 index 00000000..3b94cad8 --- /dev/null +++ b/res/app/views/docs.jade @@ -0,0 +1,16 @@ +//extends layout +block content + .row.stf-docs(ng-controller='DocsCtrl') + .col-md-10.col-md-offset-1 + .widget-container.fluid-height + .stf-docs-navigation + button.btn.btn-primary-outline.docs-back(ng-click='goBack()') + i.fa.fa-chevron-left.fa-fw + //span Back + button.btn.btn-primary-outline.docs-home(ng-click='goHome()') + i.fa.fa-home.fa-fw + //span Home + .widget-content.padded + .row + .col-md-10.col-md-offset-1 + != markdownFile.parseContent() diff --git a/res/docs/en/index.md b/res/docs/en/index.md new file mode 100644 index 00000000..092d3364 --- /dev/null +++ b/res/docs/en/index.md @@ -0,0 +1,18 @@ +# STF Documentation + +- Usage + - Getting Started + - [Remote Debugging](/#!/docs/en/remote-debug) + + - Remote Shell + - Browser Navigation + - App Uploading + - Automation + - Appium + - Others + + +- Documentation + +- License +- Contributing \ No newline at end of file diff --git a/res/docs/en/remote-debug.md b/res/docs/en/remote-debug.md new file mode 100644 index 00000000..e3a9fade --- /dev/null +++ b/res/docs/en/remote-debug.md @@ -0,0 +1,94 @@ +# Remote Debugging + +## Before starting + +To be able to use the device locally you need to have installed the [Android SDK Tools](https://developer.android.com/sdk/index.html). + + +## Debugging + +To be able to debug the remote device on a local machine, you need to do the following: + +1. On STF, after controlling a device, go to the **Dashboard** tab -> **Remote Debug** panel. + +2. There will be a text field with content like `adb connect ...`. Click and copy that text. + +3. Paste it and run it your command line. + +This will connect the device locally. + +You can check it worked, by going to your command line and typing: +```bash +adb devices +``` + + +### Android Studio + +You should be able to debug the device, however the IDE still has some bugs when using the debugger. + + +### Eclipse + +You should be able to debug the device as-is. + + + +### Chrome + +#### On the device + +On Chrome 32 and newer, you don't need to do anything on the device. + +On Chrome 32 and earlier, you need to enable USB remote debugging inside *Chrome Settings*: + +1. Open **Chrome**. +2. Go to **Settings** -> **Developer Tools**. +3. Enable **USB debugging**. + +#### On your desktop browser + +1. Open a new tab +2. Go to `chrome://inspect/#devices` on the address bar. +3. Enable **Discover USB devices** by clicking the checkbox. + +It should show a list of pages opened inside the Device's Chrome browser and WebViews. + +Now you can debug any page by clicking on **inspect**. + +See more on the [Remote Debugging on Android with Chrome](https://developer.chrome.com/devtools/docs/remote-debugging) docs. + + +### Firefox + +#### On the device + +1. Open **Firefox**. +2. Go to **Settings** -> **Developer tools**. +3. Enable **Remote debugging**. + +#### On your command line + +Go to your command line, and type: + +``` +adb forward tcp:6000 tcp:6000 +``` + +If you are using Firefox OS, type: + +``` +adb forward tcp:6000 localfilesystem:/data/local/debugger-socket +``` + + +#### On your desktop browser + +1. On the **Web Developer** menu, select **Connect**. +2. This will go to `chrome://browser/content/devtools/connect.xhtml`. +3. Press the **Connect** button. +4. On the device it will ask you to accept an **Incoming Connection**, press **OK**. + +This should show a list of pages opened inside the Device's Firefox browser and WebViews. + +See more on the [Remotely Debugging Firefox for Android](https://developer.mozilla.org/docs/Tools/Remote_Debugging/Firefox_for_Android) docs. diff --git a/res/docs/ja/index.md b/res/docs/ja/index.md new file mode 100644 index 00000000..1e4c574b --- /dev/null +++ b/res/docs/ja/index.md @@ -0,0 +1,4 @@ +# STF ドキュメント + +- 利用 + - [リモートシェル](/#!/docs/ja/remote-shell) \ No newline at end of file diff --git a/res/docs/ja/remote-shell.md b/res/docs/ja/remote-shell.md new file mode 100644 index 00000000..1cc28de6 --- /dev/null +++ b/res/docs/ja/remote-shell.md @@ -0,0 +1,110 @@ +# リモート・シェル参照 + +### ファイル一覧 +``` +ls -la +``` +シェル起動直後はディレクトリはルートです。 + + +### パッケージ名列挙 + +``` +pm list packages +``` +インストールされてるアプリのパッケージ名が列挙される。 + +パッケージ名を一部しか覚えていないときに `pm list packages [パッケージ名]` のようにフィルタリングすることができる。 + + +### パッケージ削除 + +``` +pm uninstall [パッケージ名] +``` + +その他のパッケージ・マネジャーのコマンドは [ADB pm | Android Developers](http://developer.android.com/tools/help/adb.html#pm) を参照。 + + +### ファイルの中身 + +``` +cat /sdcard/hoge.txt +``` + +読み込み権限のあるファイルの中身を簡単に確認するときに使う。 + + +### アプリの起動 + +**Activityの起動 (ACTION_VIEW + URL)** + +``` +am start -a android.intent.action.VIEW -d http://google.com +``` + +**Activityの起動(クラス名を指定)** + +``` +am start -n com.hoge.app/.FugaActivity +``` + +**サービスの起動** + +``` +am startservice ... # Intentの指定方法はActivityと同じ +``` + +**ブロードキャストの送信** + +``` +am broadcast ... # Intentの指定方法はActivityと同じ +``` + + +### キーイベント送信 + +``` +input keyevent 3 # HOMEキー +``` + +数値でキーコードを指定する。 + +キーコードは[KeyEvent | Android Developers](http://developer.android.com/reference/android/view/KeyEvent.html)を参照。 + +### 画面録画 (KitKat4.4より) + +最大３分操作情報を録画できる。 + +``` +pre screenrecord [options] +``` + +[options]は[ADB screenrecord | Android Developers](http://developer.android.com/tools/help/adb.html#screenrecord)を参照。 + +`filename`には端末側のパスを指定する。 + +``` +screenrecord /sdcard/movie/sample.mp4 +``` + +### メモリ専有状況 + +``` +dumpsys procstats [パッケージ名] +``` + +例： `dumpsys procstats com.android.chrome` + +--- + + +### その他のシェルコマンド +実行可能なシェルコマンドの一覧を取得するのに、下記のコマンドを実行する。 + +``` +ls /system/bin +``` + + +もっと詳しいリファレンスは[こちら](https://github.com/jackpal/Android-Terminal-Emulator/wiki/Android-Shell-Command-Reference)。 diff --git a/webpack.config.js b/webpack.config.js index f4f91f59..9df60c9d 100644 --- a/webpack.config.js +++ b/webpack.config.js @@ -47,18 +47,18 @@ module.exports = { { test: /\.otf$/, loader: "url-loader?limit=1&mimetype=application/font-woff" }, { test: /\.ttf$/, loader: "url-loader?limit=1&mimetype=application/font-woff" }, { test: /\.eot$/, loader: "url-loader?limit=1&mimetype=vnd.ms-fontobject" }, - { test: /\.jade/, loader: 'template-html-loader' }, - { test: /\.html/, loader: 'html-loader' }, - { test: /angular\.js/, loader: 'exports?angular'}, - { test: /angular-route\.js/, loader: 'imports?angular=angular'}, - { test: /angular-touch\.js/, loader: 'imports?angular=angular'}, - { test: /angular-animate\.js/, loader: 'imports?angular=angular'}, - { test: /angular-growl\.js/, loader: 'imports?angular=angular'}, - { test: /oboe-browser\.js/, loader: 'imports?define=>false!exports?oboe'}, - { test: /uuid\.js/, loader: 'imports?require=>undefined'}, - //{ test: /ui-bootstrap-tpls\.js/, loader: 'script'}, - { test: /dialogs\.js/, loader: 'script'}, - { test: /bluebird\.js/, loader: 'imports?require=>undefined'} + { test: /\.jade$/, loader: 'template-html-loader' }, + { test: /\.html$/, loader: 'html-loader' }, + { test: /angular\.js$/, loader: 'exports?angular'}, + { test: /angular-route\.js$/, loader: 'imports?angular=angular'}, + { test: /angular-touch\.js$/, loader: 'imports?angular=angular'}, + { test: /angular-animate\.js$/, loader: 'imports?angular=angular'}, + { test: /angular-growl\.js$/, loader: 'imports?angular=angular'}, + { test: /oboe-browser\.js$/, loader: 'imports?define=>false!exports?oboe'}, + { test: /uuid\.js$/, loader: 'imports?require=>undefined'}, + //{ test: /ui-bootstrap-tpls\.js$/, loader: 'script'}, + { test: /dialogs\.js$/, loader: 'script'}, + { test: /bluebird\.js$/, loader: 'imports?require=>undefined'} ], noParse: [ // pathutil.resource('bower_components')