autogen docs

.gitignore

@@ -20,3 +20,4 @@ package-lock.json
 yarn-error.log
 
 docs/api
+.travis.ssh.key

.travis.ssh.key.pub

@@ -0,0 +1 @@
+ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDDFM4nHSbET5V7EYNgjA8NeVfOxV0wVMdZ2YvsDzD+qPJ4+MYbvsL7ZPaSxQSn7n6ATkLHjKje5RpF/Rl9K3kucGs0P6cqJVeE0qryEteQ3Q+fYAk+bD2J9ZQ/hv/0NtLl8T+7lJUZ3WUxFH73sgph77Sw0z+kMpPaK7U2vqMBQD/7+6iJgya31wP0qW0XKDz1BjKeXgwTg10Pm4vcGsR4c2q7YIzSzBHffcyo0vJyFvOX/ZKHlZRcq/wnQMeOl/hPgf1xCENjQZmFVReQlYSw5cNNDT9HZPKekOAZFFez7/AbPiTIo/bnBYIv0mdUjr3nw8nXF505q8LiD3z/ksaaWDqe9CCLM4W0Bh7/dhP7IGPdfX0fVHLhOnYIOsG21D8rWJjMPkVRSLyEvWNAnVuObJNHoQu8VATnOxfPNnMun72IHyyFWVoADk5JcsMbzcP7gZB+5oJO7U1qpcdndtBOA3ZlF0Uz2jVZnqavoEBWT39tl3vs69hAA3aTPGclg7HMuAJOl4HsKmaUgDxqV2wCX/S4pDqmKMbmumDLX+MM0xl0gXj/zpVJp9BzdnrArkC40ivmC6TSA4wrdN0tNBlqApkH5/jxGWrcu2AXVn9PGF3+QrjW0iu+QMZCaKWDhLIQC835uFwzhnNGlx41B7uxMLuNFxKXdQ3f/cC9QMG8ew== TravisCIDeployKey

.travis.yml

@@ -13,15 +13,31 @@ cache:
     - node_modules
     - app/node_modules
 
-before_install:
-    - rm app/node_modules/.yarn-integrity || true
-    - yarn
+stages:
+  - Build
+  - name: Docs
+    if: branch = master
 
-script:
-    - scripts/build-native.js
-    - yarn run build
-    - scripts/prepackage-plugins.js
-    - scripts/build-$BUILD_FOR.js
+jobs:
+  include:
+    - stage: 'Build'
+      before_install:
+        - rm app/node_modules/.yarn-integrity || true
+        - yarn
+      script:
+        - scripts/build-native.js
+        - yarn run build
+        - scripts/prepackage-plugins.js
+        - scripts/build-$BUILD_FOR.js
+
+    - stage: 'Docs'
+      os: linux
+      script:
+        - openssl aes-256-cbc -K $encrypted_4e2fb4889ef8_key -iv $encrypted_4e2fb4889ef8_iv -in .travis.ssh.key.enc -out .travis.ssh.key -d
+        - ssh-add .travis.ssh.key
+        - yarn
+        - yarn run docs
+        - rsync -r docs/api/ root@ajenti.org:/srv/terminus-docs/
 
 dist: trusty
 sudo: false

package.json

@@ -131,6 +131,7 @@
     "watch": "cross-env TERMINUS_DEV=1 webpack --progress --color --watch",
     "start": "cross-env TERMINUS_DEV=1 electron app --debug",
     "prod": "cross-env TERMINUS_DEV=1 electron app",
+    "docs": "typedoc --out docs/api terminus-core/src && typedoc --out docs/api/terminal terminus-terminal/src && typedoc --out docs/api/settings terminus-settings/src",
     "lint": "tslint -c tslint.json -t stylish terminus-*/src/**/*.ts terminus-*/src/*.ts app/src/*.ts",
     "postinstall": "node ./scripts/install-deps.js"
   },

terminus-core/README.md

@@ -1,6 +1,8 @@
 Terminus Core Plugin
 --------------------
 
+See also: [Settings plugin API](./settings/), [Terminal plugin API](./settings/)
+
 * tabbed interface services
 * toolbar UI
 * config file management

terminus-settings/README.md

@@ -0,0 +1,23 @@
+Terminus Settings Plugin
+------------------------
+
+* tabbed settings interface
+
+Using the API:
+
+```ts
+import { SettingsTabProvider } from 'terminus-settings'
+```
+
+Exporting your subclasses:
+
+```ts
+@NgModule({
+  ...
+  providers: [
+    ...
+    { provide: SettingsTabProvider, useClass: MySettingsTab, multi: true },
+    ...
+  ]
+})
+```

terminus-settings/src/api.ts

@@ -1,3 +1,6 @@
+/**
+ * Extend to add your own settings tabs
+ */
 export abstract class SettingsTabProvider {
     id: string
     icon: string

terminus-terminal/README.md

@@ -0,0 +1,26 @@
+Terminus Terminal Plugin
+------------------------
+
+* terminal tabs
+* terminal frontends
+* session management
+* shell detection
+
+Using the API:
+
+```ts
+import { TerminalContextMenuItemProvider } from 'terminus-terminal'
+```
+
+Exporting your subclasses:
+
+```ts
+@NgModule({
+  ...
+  providers: [
+    ...
+    { provide: TerminalContextMenuItemProvider, useClass: MyContextMenu, multi: true },
+    ...
+  ]
+})
+```

terminus-terminal/src/api.ts

@@ -1,10 +1,18 @@
 import { BaseTerminalTabComponent } from './components/baseTerminalTab.component'
 
+/**
+ * Extend to automatically run actions on new terminals
+ */
 export abstract class TerminalDecorator {
-    // tslint:disable-next-line no-empty
-    attach (_terminal: BaseTerminalTabComponent): void { }
-    // tslint:disable-next-line no-empty
-    detach (_terminal: BaseTerminalTabComponent): void { }
+    /**
+     * Called when a new terminal tab starts
+     */
+    attach (terminal: BaseTerminalTabComponent): void { } // tslint:disable-line no-empty
+
+    /**
+     * Called before a terminal tab is destroyed
+     */
+    detach (terminal: BaseTerminalTabComponent): void { } // tslint:disable-line no-empty
 }
 
 export interface ResizeEvent {
@@ -17,7 +25,7 @@ export interface SessionOptions {
     command: string
     args: string[]
     cwd?: string
-    env?: any
+    env?: {[id: string]: string}
     width?: number
     height?: number
     pauseAfterExit?: boolean
@@ -37,10 +45,16 @@ export interface ITerminalColorScheme {
     colors: string[]
 }
 
+/**
+ * Extend to add more terminal color schemes
+ */
 export abstract class TerminalColorSchemeProvider {
     abstract async getSchemes (): Promise<ITerminalColorScheme[]>
 }
 
+/**
+ * Extend to add more terminal context menu items
+ */
 export abstract class TerminalContextMenuItemProvider {
     weight: number
 
@@ -52,10 +66,18 @@ export interface IShell {
     name?: string
     command: string
     args?: string[]
-    env?: any
+    env?: {[id: string]: string}
+
+    /**
+     * Base path to which shell's internal FS is relative
+     * Currently used for WSL only
+     */
     fsBase?: string
 }
 
+/**
+ * Extend to add support for more shells
+ */
 export abstract class ShellProvider {
     abstract async provide (): Promise<IShell[]>
 }

terminus-terminal/src/components/baseTerminalTab.component.ts

@@ -10,29 +10,43 @@ import { TerminalFrontendService } from '../services/terminalFrontend.service'
 import { TerminalDecorator, ResizeEvent, TerminalContextMenuItemProvider } from '../api'
 import { Frontend } from '../frontends/frontend'
 
+/**
+ * A class to base your custom terminal tabs on
+ */
 export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit, OnDestroy {
     static template = `
         <div
             #content
             class="content"
-            [style.opacity]="htermVisible ? 1 : 0"
+            [style.opacity]="frontendIsReady ? 1 : 0"
         ></div>
     `
     static styles = [require('./terminalTab.component.scss')]
 
     session: BaseSession
     @Input() zoom = 0
+
+    /** @hidden */
     @ViewChild('content') content
+
+    /** @hidden */
     @HostBinding('style.background-color') backgroundColor: string
+
+    /** @hidden */
     @HostBinding('class.top-padded') topPadded: boolean
+
     frontend: Frontend
-    sessionCloseSubscription: Subscription
-    hotkeysSubscription: Subscription
-    htermVisible = false
+
+    /** @hidden */
+    frontendIsReady = false
+
     frontendReady = new Subject<void>()
     size: ResizeEvent
+
     protected logger: Logger
     protected output = new Subject<string>()
+    private sessionCloseSubscription: Subscription
+    private hotkeysSubscription: Subscription
     private bellPlayer: HTMLAudioElement
     private termContainerSubscriptions: Subscription[] = []
 
@@ -122,6 +136,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.contextMenuProviders.sort((a, b) => a.weight - b.weight)
     }
 
+    /** @hidden */
     ngOnInit () {
         this.focused$.subscribe(() => {
             this.configure()
@@ -131,7 +146,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.frontend = this.terminalContainersService.getFrontend(this.session)
 
         this.frontend.ready$.subscribe(() => {
-            this.htermVisible = true
+            this.frontendIsReady = true
         })
 
         this.frontend.resize$.pipe(first()).subscribe(async ({ columns, rows }) => {
@@ -191,14 +206,14 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         return items
     }
 
-    detachTermContainerHandlers () {
+    protected detachTermContainerHandlers () {
         for (let subscription of this.termContainerSubscriptions) {
             subscription.unsubscribe()
         }
         this.termContainerSubscriptions = []
     }
 
-    attachTermContainerHandlers () {
+    protected attachTermContainerHandlers () {
         this.detachTermContainerHandlers()
 
         const maybeConfigure = () => {
@@ -274,6 +289,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         ]
     }
 
+    /**
+     * Feeds input into the active session
+     */
     sendInput (data: string) {
         this.session.write(data)
         if (this.config.store.terminal.scrollOnInput) {
@@ -281,6 +299,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         }
     }
 
+    /**
+     * Feeds input into the terminal frontend
+     */
     write (data: string) {
         let percentageMatch = /(^|[^\d])(\d+(\.\d+)?)%([^\d]|$)/.exec(data)
         if (percentageMatch) {
@@ -308,6 +329,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.sendInput(data)
     }
 
+    /**
+     * Applies the user settings to the terminal
+     */
     configure (): void {
         this.frontend.configure()
 
@@ -339,6 +363,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit
         this.frontend.setZoom(this.zoom)
     }
 
+    /** @hidden */
     ngOnDestroy () {
         this.frontend.detach(this.content.nativeElement)
         this.detachTermContainerHandlers()

terminus-terminal/src/components/terminalTab.component.ts

@@ -5,6 +5,7 @@ import { BaseTerminalTabComponent } from './baseTerminalTab.component'
 import { SessionOptions } from '../api'
 import { Session } from '../services/sessions.service'
 
+/** @hidden */
 @Component({
     selector: 'terminalTab',
     template: BaseTerminalTabComponent.template,

terminus-terminal/src/frontends/frontend.ts

@@ -2,6 +2,9 @@ import { Observable, Subject, AsyncSubject, ReplaySubject, BehaviorSubject } fro
 import { ResizeEvent } from '../api'
 import { ConfigService, ThemesService } from 'terminus-core'
 
+/**
+ * Extend to add support for a different VT frontend implementation
+ */
 export abstract class Frontend {
     configService: ConfigService
     themesService: ThemesService

terminus-terminal/src/services/sessions.service.ts

@@ -10,16 +10,13 @@ import { exec } from 'mz/child_process'
 import { SessionOptions } from '../api'
 import { WIN_BUILD_CONPTY_SUPPORTED, isWindowsBuild } from '../utils'
 
-let macOSNativeProcessList
 try {
-    macOSNativeProcessList = require('macos-native-processlist')
-} catch (e) { } // tslint:disable-line
+    var macOSNativeProcessList = require('macos-native-processlist') // tslint:disable-line
+} catch { } // tslint:disable-line
 
-let windowsProcessTree
 try {
-    windowsProcessTree = require('windows-process-tree')
-} catch (e) {
-} // tslint:disable-line
+    var windowsProcessTree = require('windows-process-tree') // tslint:disable-line
+} catch { } // tslint:disable-line
 
 export interface IChildProcess {
     pid: number
@@ -31,6 +28,10 @@ const windowsDirectoryRegex = /([a-zA-Z]:[^\:\[\]\?\"\<\>\|]+)/mi // tslint:dis
 const OSC1337Prefix = '\x1b]1337;'
 const OSC1337Suffix = '\x07'
 
+/**
+ * A session object for a [[BaseTerminalTabComponent]]
+ * Extend this to implement custom I/O and process management for your terminal tab
+ */
 export abstract class BaseSession {
     open: boolean
     name: string
@@ -59,10 +60,10 @@ export abstract class BaseSession {
         this.initialDataBuffer = null
     }
 
-    abstract start (options: SessionOptions)
-    abstract resize (columns, rows)
-    abstract write (data)
-    abstract kill (signal?: string)
+    abstract start (options: SessionOptions): void
+    abstract resize (columns: number, rows: number): void
+    abstract write (data: string): void
+    abstract kill (signal?: string): void
     abstract async getChildProcesses (): Promise<IChildProcess[]>
     abstract async gracefullyKillProcess (): Promise<void>
     abstract async getWorkingDirectory (): Promise<string>

terminus-terminal/src/services/terminal.service.ts

@@ -11,8 +11,12 @@ export class TerminalService {
     private shells = new AsyncSubject<IShell[]>()
     private logger: Logger
 
+    /**
+     * A fresh list of all available shells
+     */
     get shells$ (): Observable<IShell[]> { return this.shells }
 
+    /** @hidden */
     constructor (
         private app: AppService,
         private config: ConfigService,
@@ -28,12 +32,12 @@ export class TerminalService {
         })
     }
 
-    async getShells (): Promise<IShell[]> {
+    private async getShells (): Promise<IShell[]> {
         let shellLists = await Promise.all(this.config.enabledServices(this.shellProviders).map(x => x.provide()))
         return shellLists.reduce((a, b) => a.concat(b), [])
     }
 
-    async reloadShells () {
+    private async reloadShells () {
         this.shells = new AsyncSubject<IShell[]>()
         let shells = await this.getShells()
         this.logger.debug('Shells list:', shells)
@@ -41,6 +45,10 @@ export class TerminalService {
         this.shells.complete()
     }
 
+    /**
+     * Launches a new terminal with a specific shell and CWD
+     * @param pause Wait for a keypress when the shell exits
+     */
     async openTab (shell?: IShell, cwd?: string, pause?: boolean): Promise<TerminalTabComponent> {
         if (cwd && !fs.existsSync(cwd)) {
             console.warn('Ignoring non-existent CWD:', cwd)
@@ -76,6 +84,9 @@ export class TerminalService {
         }
     }
 
+    /**
+     * Open a terminal with custom session options
+     */
     openTabWithOptions (sessionOptions: SessionOptions): TerminalTabComponent {
         if (sessionOptions.runAsAdministrator && this.uac.isAvailable) {
             sessionOptions = this.uac.patchSessionOptionsForUAC(sessionOptions)

terminus-terminal/src/services/terminalFrontend.service.ts

@@ -9,6 +9,7 @@ import { BaseSession } from '../services/sessions.service'
 export class TerminalFrontendService {
     private containers = new WeakMap<BaseSession, Frontend>()
 
+    /** @hidden */
     constructor (private config: ConfigService, private themes: ThemesService) { }
 
     getFrontend (session?: BaseSession): Frontend {