From 8cf78518011a6f72030b652a6c9a8e9673fc112b Mon Sep 17 00:00:00 2001 From: Eugene Pankov Date: Thu, 7 Mar 2019 18:04:03 +0100 Subject: [PATCH] autogen docs --- .gitignore | 1 + .travis.ssh.key.enc | Bin 0 -> 3392 bytes .travis.ssh.key.pub | 1 + .travis.yml | 32 ++++++++++---- package.json | 1 + terminus-core/README.md | 2 + terminus-settings/README.md | 23 +++++++++++ terminus-settings/src/api.ts | 3 ++ terminus-terminal/README.md | 26 ++++++++++++ terminus-terminal/src/api.ts | 34 ++++++++++++--- .../components/baseTerminalTab.component.ts | 39 ++++++++++++++---- .../src/components/terminalTab.component.ts | 1 + terminus-terminal/src/frontends/frontend.ts | 3 ++ .../src/services/sessions.service.ts | 23 ++++++----- .../src/services/terminal.service.ts | 15 ++++++- .../src/services/terminalFrontend.service.ts | 1 + 16 files changed, 171 insertions(+), 34 deletions(-) create mode 100644 .travis.ssh.key.enc create mode 100644 .travis.ssh.key.pub create mode 100644 terminus-settings/README.md create mode 100644 terminus-terminal/README.md diff --git a/.gitignore b/.gitignore index 6707ec2f..22e79656 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ package-lock.json yarn-error.log docs/api +.travis.ssh.key diff --git a/.travis.ssh.key.enc b/.travis.ssh.key.enc new file mode 100644 index 0000000000000000000000000000000000000000..5f07ddbfb5ea6a87aa051b24ead04f07bc834091 GIT binary patch literal 3392 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 W2adQ}T!qTGB>~@V1dO9Gf*&HR>#%45 literal 0 HcmV?d00001 diff --git a/.travis.ssh.key.pub b/.travis.ssh.key.pub new file mode 100644 index 00000000..e534803e --- /dev/null +++ b/.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 diff --git a/.travis.yml b/.travis.yml index 4933297a..6dd634a3 100644 --- a/.travis.yml +++ b/.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 diff --git a/package.json b/package.json index de39e16a..5dca2e66 100644 --- a/package.json +++ b/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" }, diff --git a/terminus-core/README.md b/terminus-core/README.md index 84724ea4..0bf5ef39 100644 --- a/terminus-core/README.md +++ b/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 diff --git a/terminus-settings/README.md b/terminus-settings/README.md new file mode 100644 index 00000000..88706262 --- /dev/null +++ b/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 }, + ... + ] +}) +``` diff --git a/terminus-settings/src/api.ts b/terminus-settings/src/api.ts index 97faa620..9f7f4cd3 100644 --- a/terminus-settings/src/api.ts +++ b/terminus-settings/src/api.ts @@ -1,3 +1,6 @@ +/** + * Extend to add your own settings tabs + */ export abstract class SettingsTabProvider { id: string icon: string diff --git a/terminus-terminal/README.md b/terminus-terminal/README.md new file mode 100644 index 00000000..2b7a10a3 --- /dev/null +++ b/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 }, + ... + ] +}) +``` diff --git a/terminus-terminal/src/api.ts b/terminus-terminal/src/api.ts index be2e6aff..3f705337 100644 --- a/terminus-terminal/src/api.ts +++ b/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 } +/** + * 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 } diff --git a/terminus-terminal/src/components/baseTerminalTab.component.ts b/terminus-terminal/src/components/baseTerminalTab.component.ts index dc0768d6..784e7c0e 100644 --- a/terminus-terminal/src/components/baseTerminalTab.component.ts +++ b/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 = `
` 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() size: ResizeEvent + protected logger: Logger protected output = new Subject() + 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() diff --git a/terminus-terminal/src/components/terminalTab.component.ts b/terminus-terminal/src/components/terminalTab.component.ts index 59e2e18b..a99f852e 100644 --- a/terminus-terminal/src/components/terminalTab.component.ts +++ b/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, diff --git a/terminus-terminal/src/frontends/frontend.ts b/terminus-terminal/src/frontends/frontend.ts index fae63875..6efc3f69 100644 --- a/terminus-terminal/src/frontends/frontend.ts +++ b/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 diff --git a/terminus-terminal/src/services/sessions.service.ts b/terminus-terminal/src/services/sessions.service.ts index 596391af..7b87b279 100644 --- a/terminus-terminal/src/services/sessions.service.ts +++ b/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 abstract async gracefullyKillProcess (): Promise abstract async getWorkingDirectory (): Promise diff --git a/terminus-terminal/src/services/terminal.service.ts b/terminus-terminal/src/services/terminal.service.ts index cd588492..b42e2612 100644 --- a/terminus-terminal/src/services/terminal.service.ts +++ b/terminus-terminal/src/services/terminal.service.ts @@ -11,8 +11,12 @@ export class TerminalService { private shells = new AsyncSubject() private logger: Logger + /** + * A fresh list of all available shells + */ get shells$ (): Observable { return this.shells } + /** @hidden */ constructor ( private app: AppService, private config: ConfigService, @@ -28,12 +32,12 @@ export class TerminalService { }) } - async getShells (): Promise { + private async getShells (): Promise { 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() 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 { 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) diff --git a/terminus-terminal/src/services/terminalFrontend.service.ts b/terminus-terminal/src/services/terminalFrontend.service.ts index 4189a15e..3cb7b92d 100644 --- a/terminus-terminal/src/services/terminalFrontend.service.ts +++ b/terminus-terminal/src/services/terminalFrontend.service.ts @@ -9,6 +9,7 @@ import { BaseSession } from '../services/sessions.service' export class TerminalFrontendService { private containers = new WeakMap() + /** @hidden */ constructor (private config: ConfigService, private themes: ThemesService) { } getFrontend (session?: BaseSession): Frontend {