initial commit

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+/.idea
+/node_modules
+/dist

.npmignore

@@ -0,0 +1,6 @@
+.DS_Store
+/.idea
+/node_modules
+/src
+/tsconfig.json
+/.*

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Gerard Delmàs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,52 @@
+[typedoc](https://github.com/TypeStrong/typedoc) plugin to set custom source file URL links.
+
+typedoc prints a *Defined in* statement showing the source file and line for all definitions. For projects hosted on GitHub this statement will automatically link to the source file.
+
+This plugin allows to create links to files hosted on other platforms and sites like Bitbucket, GitLab or any custom site. It adds a `#L` anchor to the URL, linking to any specific line.
+
+# Installation
+
+    npm install --save-dev typedoc-plugin-sourcefile-url
+
+typedoc will automatically detect and load the plugin from `node_modules`.
+
+# Usage
+
+#### Simple Prefix
+
+    typedoc --sourcefile-url-prefix "https://www.your-repository.org/"
+
+The `--sourcefile-url-prefix` option will create URLs by prefixing the given parameter in front of each source file.
+
+*Defined in* `src/testfile.ts` will link to `https://www.your-repository.org/src/testfile.ts`.
+
+
+#### Advanced Mappings
+
+Sometimes more complex URL rules may be required. For example when grouping documentation of multiple repositories into one documentation page.
+
+Advanced mappings are described in a JSON file.
+
+    typedoc --sourcefile-url-map your-sourcefile-map.json
+
+The `your-sourcefile-map.json` structure is: 
+
+
+    [
+      {
+        "pattern": "^modules/module-one",
+        "replace": "https://www.your-repository.org/module-one/"
+      },     
+      {
+        "pattern": "^",
+        "replace": "https://www.your-repository.org/main-project/"
+      }
+    ]
+
+`pattern` is a regular expression (without enclosing slashes). Each *Defined in* statement is matched against the `pattern`. On match the `pattern` is replaced with the string from `replace` to create the URL.
+
+There can be one or more mapping rules. For each *Defined in* only the first rule that matches is applied. In the above example the last rule would match all source files that did not start with `modules/module-one`. This compares to the *Simple Prefix* option.
+
+---
+
+The options are mutually exclusive. It is not possible to use `--sourcefile-url-prefix` and `--sourcefile-url-prefix` at the same time.

package.json

@@ -0,0 +1,40 @@
+{
+  "author": "Gerard Delmàs",
+
+  "name": "typedoc-plugin-sourcefile-url",
+  "version": "1.0.2",
+  "description": "typedoc plugin to set custom source file URL links",
+
+  "homepage": "https://github.com/gdelmas/typedoc-plugin-sourcefile-url",
+  "bugs": "https://github.com/gdelmas/typedoc-plugin-sourcefile-url/issues",
+  "repository": {
+      "type" : "git",
+      "url" : "https://github.com/gdelmas/typedoc-plugin-sourcefile-url.git"
+  },
+  "license": "MIT",
+
+  "keywords": [
+    "typedocplugin",
+    "typedoc",
+    "bitbucket",
+    "gitlab"
+  ],
+
+
+  "peerDependencies": {
+    "typedoc": "^0.5.10"
+  },
+
+  "devDependencies": {
+    "typedoc": "^0.5.10",
+    "typescript": "^2.1.5"
+  },
+
+
+  "main": "dist/main.js",
+
+  "scripts": {
+    "build": "tsc",
+    "prepublish": "npm run build"
+  }
+}

src/SourcefileUrlMapPlugin.ts

@@ -0,0 +1,130 @@
+import * as Path from 'path'
+import * as FS from 'fs-extra'
+import {Component} from 'typedoc/dist/lib/utils/component'
+import {ConverterComponent} from 'typedoc/dist/lib/converter/components'
+import {Converter} from 'typedoc/dist/lib/converter/converter'
+import {Context} from 'typedoc/dist/lib/converter/context'
+import {SourceReference} from 'typedoc/dist/lib/models/sources/file'
+import {Options, OptionsReadMode} from 'typedoc/dist/lib/utils/options/options'
+
+interface Mapping {
+    pattern: RegExp,
+    replace: string
+}
+
+@Component({name: 'sourcefile-url'})
+export class SourcefileUrlMapPlugin extends ConverterComponent {
+
+    private mappings: Mapping[] | undefined
+
+    public initialize(): void
+    {
+        // read options parameter
+        const options: Options = this.application.options
+        options.read({}, OptionsReadMode.Prefetch)
+        const mapRelativePath = options.getValue('sourcefile-url-map')
+        const urlPrefix = options.getValue('sourcefile-url-prefix')
+
+        if ( (typeof mapRelativePath !== 'string') && (typeof urlPrefix !== 'string') ) {
+            return
+        }
+
+        try {
+            if ( (typeof mapRelativePath === 'string') && (typeof urlPrefix === 'string') ) {
+                throw new Error('use either --sourcefile-url-prefix or --sourcefile-url-map option')
+            }
+
+            if ( typeof mapRelativePath === 'string' ) {
+                this.readMappingJson(mapRelativePath)
+            }
+            else if ( typeof urlPrefix === 'string' ) {
+                this.mappings = [{
+                    pattern: new RegExp('^'),
+                    replace: urlPrefix
+                }]
+            }
+
+            // register handler
+            this.listenTo(this.owner, Converter.EVENT_RESOLVE_END, this.onEndResolve)
+        }
+        catch ( e ) {
+            console.error('typedoc-plugin-sourcefile-url: ' + e.message)
+        }
+    }
+
+    private readMappingJson(mapRelativePath: string): void
+    {
+        // load json
+        const mapAbsolutePath = Path.join(process.cwd(), mapRelativePath)
+
+        let json: any
+        try {
+            json = JSON.parse(FS.readFileSync(mapAbsolutePath, 'utf8'))
+        }
+        catch ( e ) {
+            throw new Error('error reading --sourcefile-url-map json file: ' + e.message)
+        }
+
+        // validate json
+        if ( !(json instanceof Array) ) {
+            throw new Error('--sourcefile-url-map json file has to have Array as root element')
+        }
+
+        this.mappings = []
+
+        // validate & process json
+        for ( const mappingJson of json ) {
+            if ( mappingJson instanceof Object && mappingJson.hasOwnProperty('pattern') && mappingJson.hasOwnProperty('replace') && typeof mappingJson['pattern'] === 'string' && typeof mappingJson['replace'] === 'string' ) {
+                let regExp: RegExp | null = null
+
+                try {
+                    regExp = new RegExp(mappingJson['pattern'])
+                }
+                catch ( e ) {
+                    throw new Error('error reading --sourcefile-url-map: ' + e.message)
+                }
+
+                this.mappings.push({
+                    pattern: regExp as RegExp,
+                    replace: mappingJson['replace']
+                })
+            }
+            else {
+                throw new Error('--sourcefile-url-map json file syntax has to be: [{"pattern": "REGEX PATTERN STRING WITHOUT ENCLOSING SLASHES", replace: "STRING"}, ETC.]')
+            }
+        }
+    }
+
+    private onEndResolve(context: Context): void
+    {
+        if ( this.mappings === undefined ) {
+            throw new Error('assertion fail')
+        }
+
+        const project = context.project
+
+        // process mappings
+        for ( const sourceFile of project.files ) {
+            for ( const mapping of this.mappings ) {
+                if ( sourceFile.fileName.match(mapping.pattern) ) {
+                    sourceFile.url = sourceFile.fileName.replace(mapping.pattern, mapping.replace)
+                    break
+                }
+            }
+        }
+
+        // add line anchors
+        for ( let key in project.reflections ) {
+            const reflection = project.reflections[key]
+
+            if ( reflection.sources ) {
+                reflection.sources.forEach((source: SourceReference) => {
+                    if (source.file && source.file.url) {
+                        source.url = source.file.url + '#L' + source.line
+                    }
+                })
+            }
+        }
+    }
+
+}

src/main.js

@@ -0,0 +1,10 @@
+var plugin = require('./SourcefileUrlMapPlugin');
+
+module.exports = function(PluginHost) {
+    var app = PluginHost.owner;
+
+    app.options.addDeclaration({name: 'sourcefile-url-map'});
+    app.options.addDeclaration({name: 'sourcefile-url-prefix'});
+
+    app.converter.addComponent('sourcefile-url-map', plugin.SourcefileUrlMapPlugin);
+};

tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es5",
+    "experimentalDecorators": true,
+    "allowJs": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "strictNullChecks": true,
+    "outDir": "dist/"
+  },
+  "include": [
+    "src/*.ts",
+    "src/*.js"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}