Merge pull request #8 from mengxinssfd/support-typedoc-v0.26

Support typedoc v0.26

Author: mengxinssfd

assets/style.css

@@ -50,7 +50,8 @@
   vertical-align: top;
   margin: 0;
 }
-.tsd-navigation.settings h3{
+.tsd-navigation.settings h3,
+.tsd-accordion-summary h3 {
   display: flex;
   align-items: center;
   font-size: 14px;

example/README.md

@@ -23,7 +23,7 @@ This project shows off some of TypeDoc's features:
 
 -   Built-in support for various TypeScript language constructs
 -   Markdown in doc comments
--   Syntax highligting in code blocks
+-   Syntax highlighting in code blocks
 
 ## Index of Examples
 
@@ -34,8 +34,9 @@ Here are some examples we wanted to highlight:
 
 ### Rendering
 
--   Markdown showcase: {@link markdownShowcase | `markdownShowcase`}
--   Syntax highlighting showcase: {@link syntaxHighlightingShowcase | `syntaxHighlightingShowcase` }
+-   External Markdown: [here](./src/documents/external-markdown.md)
+-   Markdown showcase: [here](./src/documents/markdown.md)
+-   Syntax highlighting showcase: [here](./src/documents/syntax-highlighting.md)
 
 ### Functions
 

example/media/typescript-logo.svg

@@ -2,7 +2,7 @@
   "name": "typedoc-theme-example",
   "version": "1.1.3",
   "scripts": {
-    "build:docs": "typedoc"
+    "build:docs": "typedoc --options ./typedoc.json"
   },
   "license": "MIT",
   "devDependencies": {
@@ -11,6 +11,7 @@
     "@types/react-dom": "^18.0.11",
     "lodash": "^4.17.21",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react-dom": "^18.2.0",
+    "typedoc": "^0.26.2"
   }
 }

example/package.json

@@ -42,6 +42,12 @@ function isPromiseWithCancel<T>(value: unknown): value is PromiseWithCancel<T> {
  * [real-cancellable-promise](https://github.com/srmagura/real-cancellable-promise).
  *
  * @typeParam T what the `CancellablePromise` resolves to
+ *
+ * @groupDescription Methods
+ * Descriptions can be added for groups with `@groupDescription`, which will show up in
+ * the index where groups are listed. This works for both manually created groups which
+ * are created with `@group`, and implicit groups like the `Methods` group that this
+ * description is attached to.
  */
 export class CancellablePromise<T> {
     /**
@@ -100,7 +106,7 @@ export class CancellablePromise<T> {
         onRejected?:
             | ((reason: any) => TResult2 | PromiseLike<TResult2>)
             | undefined
-            | null
+            | null,
     ): CancellablePromise<TResult1 | TResult2> {
         let fulfill;
         let reject;
@@ -147,7 +153,7 @@ export class CancellablePromise<T> {
         onRejected?:
             | ((reason: any) => TResult | PromiseLike<TResult>)
             | undefined
-            | null
+            | null,
     ): CancellablePromise<T | TResult> {
         return this.then(undefined, onRejected);
     }
@@ -161,11 +167,11 @@ export class CancellablePromise<T> {
      * @returns A Promise for the completion of the callback.
      */
     finally(
-        onFinally?: (() => void) | undefined | null
+        onFinally?: (() => void) | undefined | null,
     ): CancellablePromise<T> {
         return new CancellablePromise(
             this.promise.finally(onFinally),
-            this.cancel
+            this.cancel,
         );
     }
 
@@ -207,8 +213,8 @@ export class CancellablePromise<T> {
             T7 | PromiseLike<T7>,
             T8 | PromiseLike<T8>,
             T9 | PromiseLike<T9>,
-            T10 | PromiseLike<T10>
-        ]
+            T10 | PromiseLike<T10>,
+        ],
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10]>;
 
     static all<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
@@ -221,8 +227,8 @@ export class CancellablePromise<T> {
             T6 | PromiseLike<T6>,
             T7 | PromiseLike<T7>,
             T8 | PromiseLike<T8>,
-            T9 | PromiseLike<T9>
-        ]
+            T9 | PromiseLike<T9>,
+        ],
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7, T8, T9]>;
 
     static all<T1, T2, T3, T4, T5, T6, T7, T8>(
@@ -234,8 +240,8 @@ export class CancellablePromise<T> {
             T5 | PromiseLike<T5>,
             T6 | PromiseLike<T6>,
             T7 | PromiseLike<T7>,
-            T8 | PromiseLike<T8>
-        ]
+            T8 | PromiseLike<T8>,
+        ],
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7, T8]>;
 
     static all<T1, T2, T3, T4, T5, T6, T7>(
@@ -246,8 +252,8 @@ export class CancellablePromise<T> {
             T4 | PromiseLike<T4>,
             T5 | PromiseLike<T5>,
             T6 | PromiseLike<T6>,
-            T7 | PromiseLike<T7>
-        ]
+            T7 | PromiseLike<T7>,
+        ],
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6, T7]>;
 
     static all<T1, T2, T3, T4, T5, T6>(
@@ -257,8 +263,8 @@ export class CancellablePromise<T> {
             T3 | PromiseLike<T3>,
             T4 | PromiseLike<T4>,
             T5 | PromiseLike<T5>,
-            T6 | PromiseLike<T6>
-        ]
+            T6 | PromiseLike<T6>,
+        ],
     ): CancellablePromise<[T1, T2, T3, T4, T5, T6]>;
 
     static all<T1, T2, T3, T4, T5>(
@@ -267,33 +273,33 @@ export class CancellablePromise<T> {
             T2 | PromiseLike<T2>,
             T3 | PromiseLike<T3>,
             T4 | PromiseLike<T4>,
-            T5 | PromiseLike<T5>
-        ]
+            T5 | PromiseLike<T5>,
+        ],
     ): CancellablePromise<[T1, T2, T3, T4, T5]>;
 
     static all<T1, T2, T3, T4>(
         values: readonly [
             T1 | PromiseLike<T1>,
             T2 | PromiseLike<T2>,
             T3 | PromiseLike<T3>,
-            T4 | PromiseLike<T4>
-        ]
+            T4 | PromiseLike<T4>,
+        ],
     ): CancellablePromise<[T1, T2, T3, T4]>;
 
     static all<T1, T2, T3>(
         values: readonly [
             T1 | PromiseLike<T1>,
             T2 | PromiseLike<T2>,
-            T3 | PromiseLike<T3>
-        ]
+            T3 | PromiseLike<T3>,
+        ],
     ): CancellablePromise<[T1, T2, T3]>;
 
     static all<T1, T2>(
-        values: readonly [T1 | PromiseLike<T1>, T2 | PromiseLike<T2>]
+        values: readonly [T1 | PromiseLike<T1>, T2 | PromiseLike<T2>],
     ): CancellablePromise<[T1, T2]>;
 
     static all<T>(
-        values: readonly (T | PromiseLike<T>)[]
+        values: readonly (T | PromiseLike<T>)[],
     ): CancellablePromise<T[]>;
 
     /**
@@ -319,7 +325,7 @@ export class CancellablePromise<T> {
      * @returns A new `CancellablePromise`.
      */
     static allSettled<T extends readonly unknown[] | readonly [unknown]>(
-        values: T
+        values: T,
     ): CancellablePromise<{
         -readonly [P in keyof T]: PromiseSettledResult<
             T[P] extends PromiseLike<infer U> ? U : T[P]
@@ -335,7 +341,7 @@ export class CancellablePromise<T> {
      * promises.
      */
     static allSettled<T>(
-        values: Iterable<T>
+        values: Iterable<T>,
     ): CancellablePromise<
         PromiseSettledResult<T extends PromiseLike<infer U> ? U : T>[]
     >;
@@ -375,7 +381,7 @@ export class CancellablePromise<T> {
      * @returns a `CancellablePromise` that resolves after `ms` milliseconds.
      */
     static delay(ms: number): CancellablePromise<void> {
-        let timer: NodeJS.Timer | undefined;
+        let timer: ReturnType<typeof setTimeout> | undefined;
         let rejectFn: (reason?: any) => void = noop;
 
         const promise = new Promise<void>((resolve, reject) => {

example/src/classes/CancellablePromise.ts

@@ -99,7 +99,7 @@ export class DeliveryCustomer extends Customer {
         id: number,
         name: string,
         nextOrderNumber: string | number,
-        subscriptionType: "basic" | "enterprise"
+        subscriptionType: "basic" | "enterprise",
     ) {
         super(id, name, nextOrderNumber);
         this.subscriptionType = subscriptionType;

example/src/classes/Customer.ts

@@ -0,0 +1,92 @@
+---
+title: External Markdown
+category: Documents
+---
+
+# External Markdown
+
+It can be convenient to write long-form guides/tutorials outside of doc comments.
+To support this, TypeDoc supports including documents (like this page!) which exist
+as standalone `.md` files in your repository.
+
+## Including Documents
+
+These documents can be included in your generated documentation in a few ways.
+
+1. With the [`@document`](https://typedoc.org/tags/document/) tag.
+2. With the [projectDocuments] option.
+3. As a child of another document using yaml frontmatter.
+
+### The `@document` Tag
+
+The `@document` tag can be placed in the comments for most types to add
+a child to that reflection in the generated documentation. The content of
+the `@document` tag should simply be a path to a markdown document to be
+included in the site. As an example, the [tag which caused this file](https://github.com/TypeStrong/typedoc/blob/master/example/src/index.ts#L7)
+to be included in the example site was formatted as:
+
+```ts
+/**
+ * @document documents/external-markdown.md
+ */
+```
+
+The document path is relative to the file in which the comment appears in.
+
+### Project Documents
+
+If your project has multiple entry points, the `@document` tag cannot be used
+to place documents at the top level of the project as there is no comment location
+associated with the project. For this use case, specify the [projectDocuments]
+option. This option can be specified multiple times, or a glob may be specified
+to include multiple documents.
+
+```jsonc
+// typedoc.json
+{
+    "projectDocuments": ["documents/*.md"],
+}
+```
+
+TypeDoc's default [sorting](https://typedoc.org/options/organization/#sort) options
+will cause project documents to be re-ordered alphabetically. If not desired, sorting
+for entry points can be disabled with the [sortEntryPoints](https://typedoc.org/options/organization/#sortentrypoints)
+option.
+
+## Document Content
+
+Documents may include a yaml frontmatter section which can be used to control
+some details about the document.
+
+```yaml
+---
+title: External Markdown
+group: Documents
+category: Guides
+children:
+    - ./child.md
+    - ./child2.md
+---
+```
+
+The `title` key specifies the document name, which will be used in the sidebar
+navigation. The `group` and `category` keys are equivalent to the
+[`@group`](https://typedoc.org/tags/group/)and [`@category`](https://typedoc.org/tags/category/)
+tags and control how the document shows up in the Index section on the page
+for the reflection which owns the document. The `children` key can be used to specify
+additional documents which should be added underneath the current document.
+
+Documents may include relative links to images or other files/documents. TypeDoc
+will detect links within markdown `[text](link)` formatted links, `<a>` tags
+and `<img>` tags and automatically resolve them to other documents in the project.
+
+if a path cannot be resolved to a part of the documentation, TypeDoc will copy
+the file found to a `media` folder in your generated documentation and update the
+link to point to it, so relative links to images will still work.
+
+Documents may also include `{@link}` inline tags, which will be resolved as
+[declaration references](https://typedoc.org/guides/declaration-references/) by
+TypeDoc.
+
+[this page]: https://github.com/TypeStrong/typedoc/blob/master/example/src/documents/external-markdown.md
+[projectDocuments]: https://typedoc.org/options/input/#projectdocuments

example/src/documents/external-markdown.md

@@ -0,0 +1,58 @@
+---
+title: Markdown Showcase
+category: Documents
+---
+
+# Markdown Showcase
+
+All comments are parsed as **Markdown**. TypeDoc uses the
+[markdown-it](https://github.com/markdown-it/markdown-it) markdown parser to _convert
+comments to HTML_.
+
+TypeDoc also supports including arbitrary Markdown documents in your site. These can be top level
+documents added with the `--projectDocuments` option or added with the `@document` tag.
+
+## Symbol References
+
+You can link to other classes, members or functions using an inline link tag. See the [TypeDoc
+documentation](https://typedoc.org/tags/link/) for
+details.
+
+## Code in Doc Comments
+
+Some inline code: `npm install --save-dev typedoc`
+
+A TypeScript code block:
+
+```
+// A fabulous variable
+const x: number | string = 12
+```
+
+See {@link syntaxHighlightingShowcase | `syntaxHighlightingShowcase`} for more code blocks.
+
+## A List
+
+-   🥚 ~~Eggs~~
+-   🍞 Bread
+-   🧀 Swiss cheese
+
+## A Table
+
+| Package | Version |
+| ------- | ------- |
+| lodash  | 4.17.21 |
+| react   | 17.0.2  |
+| typedoc | 0.22.4  |
+
+A Random Shakespeare Quote
+
+---
+
+> Rebellious subjects, enemies to peace, Profaners of this neighbour-stained
+> steel,-- Will they not hear? What, ho! you men, you beasts, That quench the
+> fire of your pernicious rage With purple fountains issuing from your veins
+
+## An Image
+
+ <img src="../../media/typescript-logo.svg" width="120" />