docs: render typedoc documentation for the extension API (#921)

sourcegraph · Nov 12, 2018 · 6b42aa7 · 6b42aa7
1 parent 373d2c4
commit 6b42aa7
Show file tree

Hide file tree

Showing 7 changed files with 84 additions and 14 deletions.
diff --git a/.gitignore b/.gitignore
@@ -102,3 +102,6 @@ puppeteer/
 package-lock.json
 /dist
 sourcegraph-webapp-*.tgz
+
+# Extensions
+/packages/sourcegraph-extension-api/dist
diff --git a/package.json b/package.json
@@ -173,7 +173,8 @@
     "uglifyjs-webpack-plugin": "^1.2.4",
     "webpack": "^4.23.1",
     "webpack-dev-server": "^3.1.10",
-    "worker-loader": "^2.0.0"
+    "worker-loader": "^2.0.0",
+    "typedoc": "^0.13.0"
   },
   "dependencies": {
     "@slimsag/react-shortcuts": "^1.2.1",

diff --git a/packages/sourcegraph-extension-api/package.json b/packages/sourcegraph-extension-api/package.json
@@ -19,6 +19,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "tslint": "tslint -c tslint.json -p tsconfig.json './src/**/*.{ts,js}'"
+    "tslint": "tslint -c tslint.json -p tsconfig.json './src/**/*.{ts,js}'",
+    "docs": "typedoc"
   }
 }
diff --git a/packages/sourcegraph-extension-api/src/sourcegraph.d.ts b/packages/sourcegraph-extension-api/src/sourcegraph.d.ts
@@ -1,7 +1,14 @@
 /**
- * The Sourcegraph extension API.
+ * ## The Sourcegraph extension API
  *
- * @todo Work in progress.
+ * Sourcegraph extensions enhance your code host, code reviews, and Sourcegraph itself by adding features such as:
+ * - Code intelligence (go-to-definition, find references, hovers, etc.)
+ * - Test coverage overlays
+ * - Links to live traces, log output, and performance data for a line of code
+ * - Git blame
+ * - Usage examples for functions
+ *
+ * Check out the [extension authoring documentation](https://docs.sourcegraph.com/extensions/authoring) to get started.
  */
 declare module 'sourcegraph' {
     // tslint:disable member-access
@@ -909,6 +916,7 @@ declare module 'sourcegraph' {
      * be addressed in the beta release.
      *
      * @internal
+     * @hidden
      */
     export namespace internal {
         /**

diff --git a/packages/sourcegraph-extension-api/tsconfig.json b/packages/sourcegraph-extension-api/tsconfig.json
@@ -1,3 +1,4 @@
 {
-  "extends": "../../tsconfig.json"
+  "extends": "../../tsconfig.json",
+  "files": ["src/sourcegraph.d.ts"]
 }
diff --git a/packages/sourcegraph-extension-api/typedoc.js b/packages/sourcegraph-extension-api/typedoc.js
@@ -0,0 +1,10 @@
+module.exports = {
+  name: 'Sourcegraph extension API',
+  out: 'dist/docs/',
+  readme: 'none',
+  includes: './',
+  includeDeclarations: true,
+  mode: 'file',
+  excludeExternals: true,
+  entryPoint: '"sourcegraph"',
+}
diff --git a/yarn.lock b/yarn.lock
@@ -1790,6 +1790,13 @@
   resolved "http://registry.npmjs.org/@types/filewriter/-/filewriter-0.0.28.tgz#c054e8af4d9dd75db4e63abc76f885168714d4b3"
   integrity sha1-wFTor02d11205jq8dviFFocU1LM=
 
+"@types/fs-extra@^5.0.3":
+  version "5.0.4"
+  resolved "https://registry.npmjs.org/@types/fs-extra/-/fs-extra-5.0.4.tgz#b971134d162cc0497d221adde3dbb67502225599"
+  integrity sha512-DsknoBvD8s+RFfSGjmERJ7ZOP1HI0UZRA3FSI+Zakhrc/Gy26YQsLI+m5V5DHxroHRJqCDLKJp7Hixn8zyaF7g==
+  dependencies:
+    "@types/node" "*"
+
 "@types/get-stream@3.0.1":
   version "3.0.1"
   resolved "https://registry.npmjs.org/@types/get-stream/-/get-stream-3.0.1.tgz#ee41cb3da49936124a4be4d301c52d11b692ead6"
@@ -1841,7 +1848,12 @@
     "@types/undertaker" "*"
     "@types/vinyl-fs" "*"
 
-"@types/highlight.js@9.12.3":
+"@types/handlebars@^4.0.38":
+  version "4.0.39"
+  resolved "https://registry.npmjs.org/@types/handlebars/-/handlebars-4.0.39.tgz#961fb54db68030890942e6aeffe9f93a957807bd"
+  integrity sha512-vjaS7Q0dVqFp85QhyPSZqDKnTTCemcSHNHFvDdalO1s0Ifz5KuE64jQD5xoUkfdWwF4WpqdJEl7LsWH8rzhKJA==
+
+"@types/highlight.js@9.12.3", "@types/highlight.js@^9.12.3":
   version "9.12.3"
   resolved "https://registry.npmjs.org/@types/highlight.js/-/highlight.js-9.12.3.tgz#b672cfaac25cbbc634a0fd92c515f66faa18dbca"
   integrity sha512-pGF/zvYOACZ/gLGWdQH8zSwteQS1epp68yRcVLJMgUck/MjEn/FBYmPub9pXT8C1e4a8YZfHo1CKyV8q1vKUnQ==
@@ -1909,7 +1921,7 @@
   dependencies:
     "@types/lodash" "*"
 
-"@types/lodash@*", "@types/lodash@4.14.118", "@types/lodash@^4.14.116":
+"@types/lodash@*", "@types/lodash@4.14.118", "@types/lodash@^4.14.110", "@types/lodash@^4.14.116":
   version "4.14.118"
   resolved "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.118.tgz#247bab39bfcc6d910d4927c6e06cbc70ec376f27"
   integrity sha512-iiJbKLZbhSa6FYRip/9ZDX6HXhayXLDGY2Fqws9cOkEQ6XeKfaxB0sC541mowZJueYyMnVUmmG+al5/4fCDrgw==
@@ -1919,7 +1931,7 @@
   resolved "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.87.tgz#55f92183b048c2c64402afe472f8333f4e319a6b"
   integrity sha512-AqRC+aEF4N0LuNHtcjKtvF9OTfqZI0iaBoe3dA6m/W+/YZJBZjBmW/QIZ8fBeXC6cnytSY9tBoFBqZ9uSCeVsw==
 
-"@types/marked@0.4.2":
+"@types/marked@0.4.2", "@types/marked@^0.4.0":
   version "0.4.2"
   resolved "https://registry.npmjs.org/@types/marked/-/marked-0.4.2.tgz#64a89e53ea37f61cc0f3ee1732c555c2dbf6452f"
   integrity sha512-cDB930/7MbzaGF6U3IwSQp6XBru8xWajF5PV2YZZeV8DyiliTuld11afVztGI9+yJZ29il5E+NpGA6ooV/Cjkg==
@@ -2118,7 +2130,7 @@
     "@types/express-serve-static-core" "*"
     "@types/mime" "*"
 
-"@types/shelljs@0.8.0":
+"@types/shelljs@0.8.0", "@types/shelljs@^0.8.0":
   version "0.8.0"
   resolved "https://registry.npmjs.org/@types/shelljs/-/shelljs-0.8.0.tgz#0caa56b68baae4f68f44e0dd666ab30b098e3632"
   integrity sha512-vs1hCC8RxLHRu2bwumNyYRNrU3o8BtZhLysH5A4I98iYmA2APl6R3uNQb5ihl+WiwH0xdC9LLO+vRrXLs/Kyxg==
@@ -7869,7 +7881,7 @@ handle-thing@^1.2.5:
   resolved "http://registry.npmjs.org/handle-thing/-/handle-thing-1.2.5.tgz#fd7aad726bf1a5fd16dfc29b2f7a6601d27139c4"
   integrity sha1-/Xqtcmvxpf0W38KbL3pmAdJxOcQ=
 
-handlebars@^4.0.11, handlebars@^4.0.2:
+handlebars@^4.0.11, handlebars@^4.0.2, handlebars@^4.0.6:
   version "4.0.12"
   resolved "https://registry.npmjs.org/handlebars/-/handlebars-4.0.12.tgz#2c15c8a96d46da5e266700518ba8cb8d919d5bc5"
   integrity sha512-RhmTekP+FZL+XNhwS1Wf+bTTZpdLougwt5pcgA1tuz6Jcx0fpH/7z0qd71RKnZHBCxIRBHfBOnio4gViPemNzA==
@@ -8016,7 +8028,7 @@ he@^1.1.1:
   resolved "https://registry.npmjs.org/he/-/he-1.2.0.tgz#84ae65fa7eafb165fddb61566ae14baf05664f0f"
   integrity sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==
 
-highlight.js@^9.12.0, highlight.js@^9.13.1:
+highlight.js@^9.0.0, highlight.js@^9.12.0, highlight.js@^9.13.1:
   version "9.13.1"
   resolved "https://registry.npmjs.org/highlight.js/-/highlight.js-9.13.1.tgz#054586d53a6863311168488a0f58d6c505ce641e"
   integrity sha512-Sc28JNQNDzaH6PORtRLMvif9RSn1mYuOoX3omVjnb0+HbpPygU2ALBI0R/wsiqCb4/fcp07Gdo8g+fhtFrQl6A==
@@ -10070,6 +10082,11 @@ marked-terminal@^3.0.0, marked-terminal@^3.1.1:
     lodash.assign "^4.2.0"
     node-emoji "^1.4.1"
 
+marked@^0.4.0:
+  version "0.4.0"
+  resolved "https://registry.npmjs.org/marked/-/marked-0.4.0.tgz#9ad2c2a7a1791f10a852e0112f77b571dce10c66"
+  integrity sha512-tMsdNBgOsrUophCAFQl0XPe6Zqk/uy9gnue+jIIKhykO51hxyu6uNx7zBPy0+y/WKYVZZMspV9YeXLNdKk+iYw==
+
 "marked@^0.4.0 || ^0.5.0", marked@^0.5.0, marked@^0.5.1:
   version "0.5.1"
   resolved "https://registry.npmjs.org/marked/-/marked-0.5.1.tgz#062f43b88b02ee80901e8e8d8e6a620ddb3aa752"
@@ -10348,7 +10365,7 @@ minimalistic-crypto-utils@^1.0.0, minimalistic-crypto-utils@^1.0.1:
   resolved "https://registry.npmjs.org/minimalistic-crypto-utils/-/minimalistic-crypto-utils-1.0.1.tgz#f6c00c1c0b082246e5c4d99dfb8c7c083b2b582a"
   integrity sha1-9sAMHAsIIkblxNmd+4x8CDsrWCo=
 
-minimatch@3.0.4, minimatch@^3.0.2, minimatch@^3.0.4, minimatch@~3.0.2:
+minimatch@3.0.4, minimatch@^3.0.0, minimatch@^3.0.2, minimatch@^3.0.4, minimatch@~3.0.2:
   version "3.0.4"
   resolved "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz#5166e286457f03306064be5497e8dbb0c3d32083"
   integrity sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==
@@ -14205,7 +14222,8 @@ source-map@^0.7.2:
   integrity sha512-CkCj6giN3S+n9qrYiBTX5gystlENnRW5jZeNLHpe6aue+SrHcG5VYwujhW9s4dY31mEGsxBDrHR6oI69fTXsaQ==
 
 "sourcegraph@link:packages/sourcegraph-extension-api":
-  version "19.0.0"
+  version "0.0.0"
+  uid ""
 
 sparkles@^1.0.0:
   version "1.0.1"
@@ -15355,7 +15373,35 @@ typedarray@^0.0.6:
   resolved "https://registry.npmjs.org/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
 
-typescript@^3.1.6:
+typedoc-default-themes@^0.5.0:
+  version "0.5.0"
+  resolved "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.5.0.tgz#6dc2433e78ed8bea8e887a3acde2f31785bd6227"
+  integrity sha1-bcJDPnjti+qOiHo6zeLzF4W9Yic=
+
+typedoc@^0.13.0:
+  version "0.13.0"
+  resolved "https://registry.npmjs.org/typedoc/-/typedoc-0.13.0.tgz#9efdf352bd54873955cd161bd4b75f24a8c59dde"
+  integrity sha512-jQWtvPcV+0fiLZAXFEe70v5gqjDO6pJYJz4mlTtmGJeW2KRoIU/BEfktma6Uj8Xii7UakuZjbxFewl3UYOkU/w==
+  dependencies:
+    "@types/fs-extra" "^5.0.3"
+    "@types/handlebars" "^4.0.38"
+    "@types/highlight.js" "^9.12.3"
+    "@types/lodash" "^4.14.110"
+    "@types/marked" "^0.4.0"
+    "@types/minimatch" "3.0.3"
+    "@types/shelljs" "^0.8.0"
+    fs-extra "^7.0.0"
+    handlebars "^4.0.6"
+    highlight.js "^9.0.0"
+    lodash "^4.17.10"
+    marked "^0.4.0"
+    minimatch "^3.0.0"
+    progress "^2.0.0"
+    shelljs "^0.8.2"
+    typedoc-default-themes "^0.5.0"
+    typescript "3.1.x"
+
+typescript@3.1.x, typescript@^3.1.6:
   version "3.1.6"
   resolved "https://registry.npmjs.org/typescript/-/typescript-3.1.6.tgz#b6543a83cfc8c2befb3f4c8fba6896f5b0c9be68"
   integrity sha512-tDMYfVtvpb96msS1lDX9MEdHrW4yOuZ4Kdc4Him9oU796XldPYF/t2+uKoX0BBa0hXXwDlqYQbXY5Rzjzc5hBA==