Customize API doc theme

2025-12-22 07:00:11 +01:00 · 2016-10-21 13:20:14 +02:00 · 2016-10-21 13:20:14 +02:00 · 25e381f6f9
commit 25e381f6f9
parent b817dda06a
9 changed files with 165 additions and 0 deletions
--- a/gulpfile.js
+++ b/gulpfile.js
@ -175,6 +175,14 @@ function addPluginDTS() {
 		// Ensure consistent indentation and line endings
 		contents = cleanFile(contents);

+		// Mark events in doc!!
+		contents = contents.replace(/( \*\/\n\s+)on(.*IDisposable)/gm, function(_, m0, m1) {
+			var m = m0.match(/( +)$/);
+			var indentation = m[1];
+			return ' * @event\n' + indentation + ' */\n' + indentation + 'on' + m1;
+		});
+
+
 		data.contents = new Buffer(contents);

 		fs.writeFileSync('website/playground/monaco.d.ts.txt', contents);
--- a/monaco.d.ts
+++ b/monaco.d.ts
@ -2198,22 +2198,27 @@ declare module monaco.editor {
    export interface IModel extends IReadOnlyModel, IEditableTextModel, ITextModelWithMarkers, ITokenizedModel, ITextModelWithTrackedRanges, ITextModelWithDecorations, IEditorModel {
        /**
         * An event emitted when the contents of the model have changed.
+         * @event
         */
        onDidChangeContent(listener: (e: IModelContentChangedEvent2) => void): IDisposable;
        /**
         * An event emitted when decorations of the model have changed.
+         * @event
         */
        onDidChangeDecorations(listener: (e: IModelDecorationsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the model options have changed.
+         * @event
         */
        onDidChangeOptions(listener: (e: IModelOptionsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the language associated with the model has changed.
+         * @event
         */
        onDidChangeMode(listener: (e: IModelModeChangedEvent) => void): IDisposable;
        /**
         * An event emitted right before disposing the model.
+         * @event
         */
        onWillDispose(listener: () => void): IDisposable;
        /**
@ -2820,30 +2825,37 @@ declare module monaco.editor {
    export interface IEditor {
        /**
         * An event emitted when the content of the current model has changed.
+         * @event
         */
        onDidChangeModelContent(listener: (e: IModelContentChangedEvent2) => void): IDisposable;
        /**
         * An event emitted when the language of the current model has changed.
+         * @event
         */
        onDidChangeModelMode(listener: (e: IModelModeChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the options of the current model has changed.
+         * @event
         */
        onDidChangeModelOptions(listener: (e: IModelOptionsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the configuration of the editor has changed. (e.g. `editor.updateOptions()`)
+         * @event
         */
        onDidChangeConfiguration(listener: (e: IConfigurationChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the cursor position has changed.
+         * @event
         */
        onDidChangeCursorPosition(listener: (e: ICursorPositionChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the cursor selection has changed.
+         * @event
         */
        onDidChangeCursorSelection(listener: (e: ICursorSelectionChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the editor has been disposed.
+         * @event
         */
        onDidDispose(listener: () => void): IDisposable;
        /**
@ -3037,26 +3049,32 @@ declare module monaco.editor {
    export interface ICommonCodeEditor extends IEditor {
        /**
         * An event emitted when the model of this editor has changed (e.g. `editor.setModel()`).
+         * @event
         */
        onDidChangeModel(listener: (e: IModelChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the decorations of the current model have changed.
+         * @event
         */
        onDidChangeModelDecorations(listener: (e: IModelDecorationsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the text inside this editor gained focus (i.e. cursor blinking).
+         * @event
         */
        onDidFocusEditorText(listener: () => void): IDisposable;
        /**
         * An event emitted when the text inside this editor lost focus.
+         * @event
         */
        onDidBlurEditorText(listener: () => void): IDisposable;
        /**
         * An event emitted when the text inside this editor or an editor widget gained focus.
+         * @event
         */
        onDidFocusEditor(listener: () => void): IDisposable;
        /**
         * An event emitted when the text inside this editor or an editor widget lost focus.
+         * @event
         */
        onDidBlurEditor(listener: () => void): IDisposable;
        /**
@ -3164,6 +3182,7 @@ declare module monaco.editor {
    export interface ICommonDiffEditor extends IEditor {
        /**
         * An event emitted when the diff information computed by this diff editor has been updated.
+         * @event
         */
        onDidUpdateDiff(listener: () => void): IDisposable;
        /**
@ -3645,38 +3664,47 @@ declare module monaco.editor {
    export interface ICodeEditor extends ICommonCodeEditor {
        /**
         * An event emitted on a "mouseup".
+         * @event
         */
        onMouseUp(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "mousedown".
+         * @event
         */
        onMouseDown(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "contextmenu".
+         * @event
         */
        onContextMenu(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "mousemove".
+         * @event
         */
        onMouseMove(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "mouseleave".
+         * @event
         */
        onMouseLeave(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "keyup".
+         * @event
         */
        onKeyUp(listener: (e: IKeyboardEvent) => void): IDisposable;
        /**
         * An event emitted on a "keydown".
+         * @event
         */
        onKeyDown(listener: (e: IKeyboardEvent) => void): IDisposable;
        /**
         * An event emitted when the layout of the editor has changed.
+         * @event
         */
        onDidLayoutChange(listener: (e: EditorLayoutInfo) => void): IDisposable;
        /**
         * An event emitted when the scroll in the editor has changed.
+         * @event
         */
        onDidScrollChange(listener: (e: IScrollEvent) => void): IDisposable;
        /**
--- a/website/playground/monaco.d.ts.txt
+++ b/website/playground/monaco.d.ts.txt
@ -2198,22 +2198,27 @@ declare module monaco.editor {
    export interface IModel extends IReadOnlyModel, IEditableTextModel, ITextModelWithMarkers, ITokenizedModel, ITextModelWithTrackedRanges, ITextModelWithDecorations, IEditorModel {
        /**
         * An event emitted when the contents of the model have changed.
+         * @event
         */
        onDidChangeContent(listener: (e: IModelContentChangedEvent2) => void): IDisposable;
        /**
         * An event emitted when decorations of the model have changed.
+         * @event
         */
        onDidChangeDecorations(listener: (e: IModelDecorationsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the model options have changed.
+         * @event
         */
        onDidChangeOptions(listener: (e: IModelOptionsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the language associated with the model has changed.
+         * @event
         */
        onDidChangeMode(listener: (e: IModelModeChangedEvent) => void): IDisposable;
        /**
         * An event emitted right before disposing the model.
+         * @event
         */
        onWillDispose(listener: () => void): IDisposable;
        /**
@ -2820,30 +2825,37 @@ declare module monaco.editor {
    export interface IEditor {
        /**
         * An event emitted when the content of the current model has changed.
+         * @event
         */
        onDidChangeModelContent(listener: (e: IModelContentChangedEvent2) => void): IDisposable;
        /**
         * An event emitted when the language of the current model has changed.
+         * @event
         */
        onDidChangeModelMode(listener: (e: IModelModeChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the options of the current model has changed.
+         * @event
         */
        onDidChangeModelOptions(listener: (e: IModelOptionsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the configuration of the editor has changed. (e.g. `editor.updateOptions()`)
+         * @event
         */
        onDidChangeConfiguration(listener: (e: IConfigurationChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the cursor position has changed.
+         * @event
         */
        onDidChangeCursorPosition(listener: (e: ICursorPositionChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the cursor selection has changed.
+         * @event
         */
        onDidChangeCursorSelection(listener: (e: ICursorSelectionChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the editor has been disposed.
+         * @event
         */
        onDidDispose(listener: () => void): IDisposable;
        /**
@ -3037,26 +3049,32 @@ declare module monaco.editor {
    export interface ICommonCodeEditor extends IEditor {
        /**
         * An event emitted when the model of this editor has changed (e.g. `editor.setModel()`).
+         * @event
         */
        onDidChangeModel(listener: (e: IModelChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the decorations of the current model have changed.
+         * @event
         */
        onDidChangeModelDecorations(listener: (e: IModelDecorationsChangedEvent) => void): IDisposable;
        /**
         * An event emitted when the text inside this editor gained focus (i.e. cursor blinking).
+         * @event
         */
        onDidFocusEditorText(listener: () => void): IDisposable;
        /**
         * An event emitted when the text inside this editor lost focus.
+         * @event
         */
        onDidBlurEditorText(listener: () => void): IDisposable;
        /**
         * An event emitted when the text inside this editor or an editor widget gained focus.
+         * @event
         */
        onDidFocusEditor(listener: () => void): IDisposable;
        /**
         * An event emitted when the text inside this editor or an editor widget lost focus.
+         * @event
         */
        onDidBlurEditor(listener: () => void): IDisposable;
        /**
@ -3164,6 +3182,7 @@ declare module monaco.editor {
    export interface ICommonDiffEditor extends IEditor {
        /**
         * An event emitted when the diff information computed by this diff editor has been updated.
+         * @event
         */
        onDidUpdateDiff(listener: () => void): IDisposable;
        /**
@ -3645,38 +3664,47 @@ declare module monaco.editor {
    export interface ICodeEditor extends ICommonCodeEditor {
        /**
         * An event emitted on a "mouseup".
+         * @event
         */
        onMouseUp(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "mousedown".
+         * @event
         */
        onMouseDown(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "contextmenu".
+         * @event
         */
        onContextMenu(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "mousemove".
+         * @event
         */
        onMouseMove(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "mouseleave".
+         * @event
         */
        onMouseLeave(listener: (e: IEditorMouseEvent) => void): IDisposable;
        /**
         * An event emitted on a "keyup".
+         * @event
         */
        onKeyUp(listener: (e: IKeyboardEvent) => void): IDisposable;
        /**
         * An event emitted on a "keydown".
+         * @event
         */
        onKeyDown(listener: (e: IKeyboardEvent) => void): IDisposable;
        /**
         * An event emitted when the layout of the editor has changed.
+         * @event
         */
        onDidLayoutChange(listener: (e: EditorLayoutInfo) => void): IDisposable;
        /**
         * An event emitted when the scroll in the editor has changed.
+         * @event
         */
        onDidScrollChange(listener: (e: IScrollEvent) => void): IDisposable;
        /**
--- a/website/typedoc-theme/assets/css/main.css
+++ b/website/typedoc-theme/assets/css/main.css
@ -863,3 +863,11 @@ input[type=checkbox]:checked + .tsd-widget:before { background-position: -160px
  .tsd-select .tsd-select-label:before { background-position: -280px 0; } }

 img { max-width: 100%; }
+
+/* MONACO_CHANGE */
+.tsd-breadcrumb li:after {
+  content: ".";
+}
+.tsd-breadcrumb li:last-of-type:after {
+  content: "";
+}
--- a/website/typedoc-theme/helpers/sortModelGroups.js
+++ b/website/typedoc-theme/helpers/sortModelGroups.js
@ -0,0 +1,78 @@
+
+// https://github.com/TypeStrong/typedoc/blob/master/src/lib/models/reflections/abstract.ts#L37
+var ReflectionKind = {
+    Global: 0,
+    ExternalModule: 1,
+    Module: 2,
+    Enum: 4,
+    EnumMember: 16,
+    Variable: 32,
+    Function: 64,
+    Class: 128,
+    Interface: 256,
+    Constructor: 512,
+    Property: 1024,
+    Method: 2048,
+    CallSignature: 4096,
+    IndexSignature: 8192,
+    ConstructorSignature: 16384,
+    Parameter: 32768,
+    TypeLiteral: 65536,
+    TypeParameter: 131072,
+    Accessor: 262144,
+    GetSignature: 524288,
+    SetSignature: 1048576,
+    ObjectLiteral: 2097152,
+    TypeAlias: 4194304,
+    Event: 8388608,
+}
+// https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/plugins/GroupPlugin.ts#L20
+var WEIGHTS = [
+    ReflectionKind.Global,
+    ReflectionKind.ExternalModule,
+    ReflectionKind.Module,
+
+    ReflectionKind.Function,
+    ReflectionKind.Variable,
+
+    ReflectionKind.Enum,
+    ReflectionKind.EnumMember,
+    ReflectionKind.Class,
+    ReflectionKind.Interface,
+    ReflectionKind.TypeAlias,
+
+    ReflectionKind.Constructor,
+    ReflectionKind.Event,
+    ReflectionKind.Property,
+    ReflectionKind.Accessor,
+    ReflectionKind.Method,
+    ReflectionKind.ObjectLiteral,
+
+    ReflectionKind.Parameter,
+    ReflectionKind.TypeParameter,
+    ReflectionKind.TypeLiteral,
+    ReflectionKind.CallSignature,
+    ReflectionKind.ConstructorSignature,
+    ReflectionKind.IndexSignature,
+    ReflectionKind.GetSignature,
+    ReflectionKind.SetSignature,
+];
+
+// https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/plugins/GroupPlugin.ts#L235
+function sortFunc(a, b) {
+    var aWeight = WEIGHTS.indexOf(a.kind);
+    var bWeight = WEIGHTS.indexOf(b.kind);
+    if (aWeight == bWeight) {
+        if (a.flags.isStatic && !b.flags.isStatic) return 1;
+        if (!a.flags.isStatic && b.flags.isStatic) return -1;
+        if (a.name == b.name) return 0;
+        return a.name > b.name ? 1 : -1;
+    } else return aWeight - bWeight;
+}
+module.exports = {
+  sortModelGroups: function ( model ) {
+    if (model.groups) {
+      model.groups.sort(sortFunc);
+    }
+  }
+}
--- a/website/typedoc-theme/layouts/default.hbs
+++ b/website/typedoc-theme/layouts/default.hbs
@ -8,7 +8,9 @@
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <link rel="stylesheet" href="{{relativeURL "assets/css/main.css"}}">
+    {{!--MONACO_CHANGE
    <script src="{{relativeURL "assets/js/modernizr.js"}}"></script>
+    MONACO_CHANGE--}}
 </head>
 <body>

--- a/website/typedoc-theme/partials/header.hbs
+++ b/website/typedoc-theme/partials/header.hbs
@ -13,9 +13,13 @@
                        <li class="state failure">The search index is not available</li>
                    </ul>

+                    {{!--MONACO_CHANGE
                    <a href="{{relativeURL "index.html"}}" class="title">{{project.name}}</a>
+                    MONACO_CHANGE--}}
+                    <a href="https://microsoft.github.io/monaco-editor/" class="title">{{project.name}}</a>
                </div>

+                {{!--MONACO_CHANGE
                <div class="table-cell" id="tsd-widgets">
                    <div id="tsd-filter">
                        <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
@ -46,6 +50,7 @@

                    <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
                </div>
+                MONACO_CHANGE--}}
            </div>
        </div>
    </div>
@ -54,6 +59,7 @@
            <ul class="tsd-breadcrumb">
                {{#with model}}{{> breadcrumb}}{{/with}}
            </ul>
+            {{!--MONACO_CHANGE
            <h1>{{#compact}}
                {{model.kindString}}&nbsp;
                {{model.name}}
@ -66,6 +72,7 @@
                    &gt;
                {{/if}}
            {{/compact}}</h1>
+            MONACO_CHANGE--}}
        </div>
    </div>
 </header>
--- a/website/typedoc-theme/partials/member.sources.hbs
+++ b/website/typedoc-theme/partials/member.sources.hbs
@ -14,7 +14,10 @@
                {{#if url}}
                    <li>Defined in <a href="{{url}}">{{fileName}}:{{line}}</a></li>
                {{else}}
+                    {{!--MONACO_CHANGE
                    <li>Defined in {{fileName}}:{{line}}</li>
+                    MONACO_CHANGE--}}
+                    <li>Defined in <a href="https://github.com/Microsoft/monaco-editor/blob/master/monaco.d.ts#L{{line}}">{{fileName}}:{{line}}</a></li>
                {{/if}}
            {{/each}}
        </ul>
--- a/website/typedoc-theme/templates/reflection.hbs
+++ b/website/typedoc-theme/templates/reflection.hbs
@ -73,6 +73,9 @@
    </section>
 {{/if}}

+{{!--MONACO_CHANGE--}}
+{{sortModelGroups model}}
+{{!--MONACO_CHANGE--}}
 {{#with model}}
    {{> index}}
    {{> members}}