From 09fe47fe32d292145c9cfd265be7fd6a95d8ea1d Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Sun, 16 Jun 2024 14:18:21 -0600 Subject: [PATCH] Update example for 0.26 --- example/README.md | 5 +- example/package-lock.json | 148 ++++++++----------- example/package.json | 12 +- example/src/classes/CancellablePromise.ts | 2 +- example/src/documents/external-markdown.md | 93 ++++++++++++ example/src/documents/markdown.md | 2 +- example/src/documents/syntax-highlighting.md | 4 + example/src/index.ts | 1 + example/typedoc.json | 12 ++ 9 files changed, 183 insertions(+), 96 deletions(-) create mode 100644 example/src/documents/external-markdown.md diff --git a/example/README.md b/example/README.md index cbb6bdf57..f0c79be06 100644 --- a/example/README.md +++ b/example/README.md @@ -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 diff --git a/example/package-lock.json b/example/package-lock.json index 216c4bec6..7bd581806 100644 --- a/example/package-lock.json +++ b/example/package-lock.json @@ -9,21 +9,22 @@ "version": "0.0.0", "license": "Apache-2.0", "dependencies": { - "@types/lodash": "^4.14.177", - "@types/react": "^17.0.37", - "@types/react-dom": "^17.0.11", + "@types/lodash": "^4.17.5", + "@types/react": "^18.3.3", + "@types/react-dom": "^18.3.0", "lodash": "^4.17.21", - "react": "^17.0.2", - "react-dom": "^17.0.2" + "react": "^18.3.1", + "react-dom": "^18.3.1" }, "devDependencies": { - "typescript": "^5.3.2" + "typescript": "^5.4.5" } }, "node_modules/@types/lodash": { - "version": "4.14.177", - "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.177.tgz", - "integrity": "sha512-0fDwydE2clKe9MNfvXHBHF9WEahRuj+msTuQqOmAApNORFvhMYZKNGGJdCzuhheVjMps/ti0Ak/iJPACMaevvw==" + "version": "4.17.5", + "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.17.5.tgz", + "integrity": "sha512-MBIOHVZqVqgfro1euRDWX7OO0fBVUUMrN6Pwm8LQsz8cWhEpihlvR70ENj3f40j58TNxZaWv2ndSkInykNBBJw==", + "license": "MIT" }, "node_modules/@types/prop-types": { "version": "15.7.4", @@ -31,28 +32,24 @@ "integrity": "sha512-rZ5drC/jWjrArrS8BR6SIr4cWpW09RNTYt9AMZo3Jwwif+iacXAqgVjm0B0Bv/S1jhDXKHqRVNCbACkJ89RAnQ==" }, "node_modules/@types/react": { - "version": "17.0.37", - "resolved": "https://registry.npmjs.org/@types/react/-/react-17.0.37.tgz", - "integrity": "sha512-2FS1oTqBGcH/s0E+CjrCCR9+JMpsu9b69RTFO+40ua43ZqP5MmQ4iUde/dMjWR909KxZwmOQIFq6AV6NjEG5xg==", + "version": "18.3.3", + "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.3.tgz", + "integrity": "sha512-hti/R0pS0q1/xx+TsI73XIqk26eBsISZ2R0wUijXIngRK9R/e7Xw/cXVxQK7R5JjW+SV4zGcn5hXjudkN/pLIw==", + "license": "MIT", "dependencies": { "@types/prop-types": "*", - "@types/scheduler": "*", "csstype": "^3.0.2" } }, "node_modules/@types/react-dom": { - "version": "17.0.11", - "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-17.0.11.tgz", - "integrity": "sha512-f96K3k+24RaLGVu/Y2Ng3e1EbZ8/cVJvypZWd7cy0ofCBaf2lcM46xNhycMZ2xGwbBjRql7hOlZ+e2WlJ5MH3Q==", + "version": "18.3.0", + "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.0.tgz", + "integrity": "sha512-EhwApuTmMBmXuFOikhQLIBUn6uFg81SwLMOAUgodJF14SOBOCMdU04gDoYi0WOJJHD144TL32z4yDqCW3dnkQg==", + "license": "MIT", "dependencies": { "@types/react": "*" } }, - "node_modules/@types/scheduler": { - "version": "0.16.2", - "resolved": "https://registry.npmjs.org/@types/scheduler/-/scheduler-0.16.2.tgz", - "integrity": "sha512-hppQEBDmlwhFAXKJX2KnWLYu5yMfi91yazPb2l+lbJiwW+wdo1gNeRA+3RgNSO39WYX2euey41KEwnqesU2Jew==" - }, "node_modules/csstype": { "version": "3.0.9", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.0.9.tgz", @@ -79,53 +76,46 @@ "loose-envify": "cli.js" } }, - "node_modules/object-assign": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", - "integrity": "sha1-IQmtx5ZYh8/AXLvUQsrIv7s2CGM=", - "engines": { - "node": ">=0.10.0" - } - }, "node_modules/react": { - "version": "17.0.2", - "resolved": "https://registry.npmjs.org/react/-/react-17.0.2.tgz", - "integrity": "sha512-gnhPt75i/dq/z3/6q/0asP78D0u592D5L1pd7M8P+dck6Fu/jJeL6iVVK23fptSUZj8Vjf++7wXA8UNclGQcbA==", + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz", + "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==", + "license": "MIT", "dependencies": { - "loose-envify": "^1.1.0", - "object-assign": "^4.1.1" + "loose-envify": "^1.1.0" }, "engines": { "node": ">=0.10.0" } }, "node_modules/react-dom": { - "version": "17.0.2", - "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-17.0.2.tgz", - "integrity": "sha512-s4h96KtLDUQlsENhMn1ar8t2bEa+q/YAtj8pPPdIjPDGBDIVNsrD9aXNWqspUe6AzKCIG0C1HZZLqLV7qpOBGA==", + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz", + "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==", + "license": "MIT", "dependencies": { "loose-envify": "^1.1.0", - "object-assign": "^4.1.1", - "scheduler": "^0.20.2" + "scheduler": "^0.23.2" }, "peerDependencies": { - "react": "17.0.2" + "react": "^18.3.1" } }, "node_modules/scheduler": { - "version": "0.20.2", - "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.20.2.tgz", - "integrity": "sha512-2eWfGgAqqWFGqtdMmcL5zCMK1U8KlXv8SQFGglL3CEtd0aDVDWgeF/YoCmvln55m5zSk3J/20hTaSBeSObsQDQ==", + "version": "0.23.2", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz", + "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==", + "license": "MIT", "dependencies": { - "loose-envify": "^1.1.0", - "object-assign": "^4.1.1" + "loose-envify": "^1.1.0" } }, "node_modules/typescript": { - "version": "5.3.2", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.3.2.tgz", - "integrity": "sha512-6l+RyNy7oAHDfxC4FzSJcz9vnjTKxrLpDG5M2Vu4SHRVNg6xzqZp6LYSR9zjqQTu8DU/f5xwxUdADOkbrIX2gQ==", + "version": "5.4.5", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz", + "integrity": "sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==", "dev": true, + "license": "Apache-2.0", "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -137,9 +127,9 @@ }, "dependencies": { "@types/lodash": { - "version": "4.14.177", - "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.14.177.tgz", - "integrity": "sha512-0fDwydE2clKe9MNfvXHBHF9WEahRuj+msTuQqOmAApNORFvhMYZKNGGJdCzuhheVjMps/ti0Ak/iJPACMaevvw==" + "version": "4.17.5", + "resolved": "https://registry.npmjs.org/@types/lodash/-/lodash-4.17.5.tgz", + "integrity": "sha512-MBIOHVZqVqgfro1euRDWX7OO0fBVUUMrN6Pwm8LQsz8cWhEpihlvR70ENj3f40j58TNxZaWv2ndSkInykNBBJw==" }, "@types/prop-types": { "version": "15.7.4", @@ -147,28 +137,22 @@ "integrity": "sha512-rZ5drC/jWjrArrS8BR6SIr4cWpW09RNTYt9AMZo3Jwwif+iacXAqgVjm0B0Bv/S1jhDXKHqRVNCbACkJ89RAnQ==" }, "@types/react": { - "version": "17.0.37", - "resolved": "https://registry.npmjs.org/@types/react/-/react-17.0.37.tgz", - "integrity": "sha512-2FS1oTqBGcH/s0E+CjrCCR9+JMpsu9b69RTFO+40ua43ZqP5MmQ4iUde/dMjWR909KxZwmOQIFq6AV6NjEG5xg==", + "version": "18.3.3", + "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.3.tgz", + "integrity": "sha512-hti/R0pS0q1/xx+TsI73XIqk26eBsISZ2R0wUijXIngRK9R/e7Xw/cXVxQK7R5JjW+SV4zGcn5hXjudkN/pLIw==", "requires": { "@types/prop-types": "*", - "@types/scheduler": "*", "csstype": "^3.0.2" } }, "@types/react-dom": { - "version": "17.0.11", - "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-17.0.11.tgz", - "integrity": "sha512-f96K3k+24RaLGVu/Y2Ng3e1EbZ8/cVJvypZWd7cy0ofCBaf2lcM46xNhycMZ2xGwbBjRql7hOlZ+e2WlJ5MH3Q==", + "version": "18.3.0", + "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.0.tgz", + "integrity": "sha512-EhwApuTmMBmXuFOikhQLIBUn6uFg81SwLMOAUgodJF14SOBOCMdU04gDoYi0WOJJHD144TL32z4yDqCW3dnkQg==", "requires": { "@types/react": "*" } }, - "@types/scheduler": { - "version": "0.16.2", - "resolved": "https://registry.npmjs.org/@types/scheduler/-/scheduler-0.16.2.tgz", - "integrity": "sha512-hppQEBDmlwhFAXKJX2KnWLYu5yMfi91yazPb2l+lbJiwW+wdo1gNeRA+3RgNSO39WYX2euey41KEwnqesU2Jew==" - }, "csstype": { "version": "3.0.9", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.0.9.tgz", @@ -192,43 +176,35 @@ "js-tokens": "^3.0.0 || ^4.0.0" } }, - "object-assign": { - "version": "4.1.1", - "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", - "integrity": "sha1-IQmtx5ZYh8/AXLvUQsrIv7s2CGM=" - }, "react": { - "version": "17.0.2", - "resolved": "https://registry.npmjs.org/react/-/react-17.0.2.tgz", - "integrity": "sha512-gnhPt75i/dq/z3/6q/0asP78D0u592D5L1pd7M8P+dck6Fu/jJeL6iVVK23fptSUZj8Vjf++7wXA8UNclGQcbA==", + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz", + "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==", "requires": { - "loose-envify": "^1.1.0", - "object-assign": "^4.1.1" + "loose-envify": "^1.1.0" } }, "react-dom": { - "version": "17.0.2", - "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-17.0.2.tgz", - "integrity": "sha512-s4h96KtLDUQlsENhMn1ar8t2bEa+q/YAtj8pPPdIjPDGBDIVNsrD9aXNWqspUe6AzKCIG0C1HZZLqLV7qpOBGA==", + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz", + "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==", "requires": { "loose-envify": "^1.1.0", - "object-assign": "^4.1.1", - "scheduler": "^0.20.2" + "scheduler": "^0.23.2" } }, "scheduler": { - "version": "0.20.2", - "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.20.2.tgz", - "integrity": "sha512-2eWfGgAqqWFGqtdMmcL5zCMK1U8KlXv8SQFGglL3CEtd0aDVDWgeF/YoCmvln55m5zSk3J/20hTaSBeSObsQDQ==", + "version": "0.23.2", + "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz", + "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==", "requires": { - "loose-envify": "^1.1.0", - "object-assign": "^4.1.1" + "loose-envify": "^1.1.0" } }, "typescript": { - "version": "5.3.2", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.3.2.tgz", - "integrity": "sha512-6l+RyNy7oAHDfxC4FzSJcz9vnjTKxrLpDG5M2Vu4SHRVNg6xzqZp6LYSR9zjqQTu8DU/f5xwxUdADOkbrIX2gQ==", + "version": "5.4.5", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.5.tgz", + "integrity": "sha512-vcI4UpRgg81oIRUFwR0WSIHKt11nJ7SAVlYNIu+QpqeyXP+gpQJy/Z4+F0aGxSE4MqwjyXvW/TzgkLAx2AGHwQ==", "dev": true } } diff --git a/example/package.json b/example/package.json index d12880461..678503e4e 100644 --- a/example/package.json +++ b/example/package.json @@ -11,14 +11,14 @@ "typedoc": "node ../bin/typedoc" }, "dependencies": { - "@types/lodash": "^4.14.177", - "@types/react": "^17.0.37", - "@types/react-dom": "^17.0.11", + "@types/lodash": "^4.17.5", + "@types/react": "^18.3.3", + "@types/react-dom": "^18.3.0", "lodash": "^4.17.21", - "react": "^17.0.2", - "react-dom": "^17.0.2" + "react": "^18.3.1", + "react-dom": "^18.3.1" }, "devDependencies": { - "typescript": "^5.3.2" + "typescript": "^5.4.5" } } diff --git a/example/src/classes/CancellablePromise.ts b/example/src/classes/CancellablePromise.ts index 12427f9a5..822f9ae8e 100644 --- a/example/src/classes/CancellablePromise.ts +++ b/example/src/classes/CancellablePromise.ts @@ -381,7 +381,7 @@ export class CancellablePromise { * @returns a `CancellablePromise` that resolves after `ms` milliseconds. */ static delay(ms: number): CancellablePromise { - let timer: NodeJS.Timer | undefined; + let timer: ReturnType | undefined; let rejectFn: (reason?: any) => void = noop; const promise = new Promise((resolve, reject) => { diff --git a/example/src/documents/external-markdown.md b/example/src/documents/external-markdown.md new file mode 100644 index 000000000..78ec52bd4 --- /dev/null +++ b/example/src/documents/external-markdown.md @@ -0,0 +1,93 @@ +--- +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, `` tags +and `` 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 diff --git a/example/src/documents/markdown.md b/example/src/documents/markdown.md index 41788efd3..2683eb988 100644 --- a/example/src/documents/markdown.md +++ b/example/src/documents/markdown.md @@ -55,4 +55,4 @@ A Random Shakespeare Quote ## An Image - + diff --git a/example/src/documents/syntax-highlighting.md b/example/src/documents/syntax-highlighting.md index 97348b42a..6bb96094a 100644 --- a/example/src/documents/syntax-highlighting.md +++ b/example/src/documents/syntax-highlighting.md @@ -6,6 +6,10 @@ category: Documents TypeDoc supports code blocks in Markdown and uses [Shiki](https://shiki.matsu.io/) to provide syntax highlighting. +TypeDoc supports all languages supported by Shiki, but does not load all of +them by default. The `highlightLanguages` option can be used to customize +which languages are loaded for highlighting. + If no language is specified, the code block is assumed to be TypeScript: ``` diff --git a/example/src/index.ts b/example/src/index.ts index 7aad6b089..1347b8fff 100644 --- a/example/src/index.ts +++ b/example/src/index.ts @@ -4,6 +4,7 @@ * React Components -- This description is added with the `@categoryDescription` tag * on the entry point in src/index.ts * + * @document documents/external-markdown.md * @document documents/markdown.md * @document documents/syntax-highlighting.md */ diff --git a/example/typedoc.json b/example/typedoc.json index 90174d903..522386c2f 100644 --- a/example/typedoc.json +++ b/example/typedoc.json @@ -17,5 +17,17 @@ }, "sidebarLinks": { "API": "https://typedoc.org/api" + }, + "highlightLanguages": [ + "typescript", + "tsx", + "css", + "json", + "jsonc", + "python", + "yaml" + ], + "markdownItOptions": { + "html": true } }