Merge pull request #2210 from TypeStrong/beta

v0.24

.config/typedoc.json

@@ -12,11 +12,11 @@
         "MeaningKeywords"
     ],
     "sort": ["kind", "instance-first", "required-first", "alphabetical"],
-    "entryPoints": ["../src"],
-    "entryPointStrategy": "resolve",
+    "entryPoints": ["../src/index.ts"],
     "excludeExternals": true,
     "excludeInternal": false,
     "excludePrivate": true,
+    "excludeReferences": true,
     "treatWarningsAsErrors": false,
     "validation": {
         "notExported": true,
@@ -36,6 +36,6 @@
         "Enumerations": 2.0,
         "Type Aliases": 2.0
     },
-    "searchInComments": true,
+    "includeVersion": true,
     "logLevel": "Verbose"
 }

.eslintrc

@@ -30,7 +30,6 @@
         // Would be nice to lint these, but they shouldn't be included in the project,
         // so we need a second eslint config file.
         "example",
-        "src/codegen",
         "src/test/converter",
         "src/test/converter2",
         "src/test/module",
@@ -41,33 +40,34 @@
         "bin"
     ],
     "rules": {
-        "@typescript-eslint/no-floating-promises": 1,
+        "@typescript-eslint/no-floating-promises": "error",
+        "@typescript-eslint/await-thenable": "error",
 
         // This one is just annoying since it complains at incomplete code
-        "no-empty": 0,
+        "no-empty": "off",
 
         // This rule is factually incorrect. Interfaces which extend some type alias can be used to introduce
         // new type names. This is useful particularly when dealing with mixins.
-        "@typescript-eslint/no-empty-interface": 0,
+        "@typescript-eslint/no-empty-interface": "off",
 
         // We still use `any` fairly frequently...
-        "@typescript-eslint/ban-types": 0,
-        "@typescript-eslint/no-explicit-any": 0,
+        "@typescript-eslint/ban-types": "off",
+        "@typescript-eslint/no-explicit-any": "off",
 
         // Really annoying, doesn't provide any value.
-        "@typescript-eslint/no-empty-function": 0,
+        "@typescript-eslint/no-empty-function": "off",
 
         // Declaration merging with a namespace is a necessary tool when working with enums.
-        "@typescript-eslint/no-namespace": 0,
+        "@typescript-eslint/no-namespace": "off",
 
         // Reported by TypeScript
-        "@typescript-eslint/no-unused-vars": 0,
+        "@typescript-eslint/no-unused-vars": "off",
 
-        "no-console": 1,
+        "no-console": "warn",
 
         // Feel free to turn one of these back on and submit a PR!
-        "@typescript-eslint/no-non-null-assertion": 0,
-        "@typescript-eslint/explicit-module-boundary-types": 0,
+        "@typescript-eslint/no-non-null-assertion": "off",
+        "@typescript-eslint/explicit-module-boundary-types": "off",
 
         "no-restricted-syntax": [
             "warn",

.github/workflows/ci.yml

@@ -29,6 +29,6 @@ jobs:
             - name: Lint
               run: npm run lint -- --max-warnings 0
             - name: Circular dependency check
-              uses: gerrit0/circular-dependency-check@v1
+              uses: gerrit0/circular-dependency-check@v2
               with:
                   entry: dist/index.js

.github/workflows/publish-beta.yml

@@ -9,7 +9,7 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             - name: Checkout repository
-              uses: actions/checkout@v2
+              uses: actions/checkout@v3
             - id: check
               uses: EndBug/version-check@v1
               with:

.github/workflows/publish-lts.yml

@@ -9,14 +9,14 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             - name: Checkout repository
-              uses: actions/checkout@v2
+              uses: actions/checkout@v3
             - id: check
               uses: EndBug/version-check@v1
               with:
                   diff-search: true
             - name: Set up Node
               if: steps.check.outputs.changed == 'true'
-              uses: actions/setup-node@v1
+              uses: actions/setup-node@v3
               with:
                   node-version: "16"
             - name: Upgrade npm

.github/workflows/visual-regression.yml

@@ -5,9 +5,9 @@ jobs:
         runs-on: ubuntu-latest
         steps:
             - name: Checkout repository
-              uses: actions/checkout@v2
+              uses: actions/checkout@v3
             - name: Set up Node
-              uses: actions/setup-node@v1
+              uses: actions/setup-node@v3
               with:
                   node-version: 16
             - name: Upgrade npm

.gitignore

@@ -14,6 +14,7 @@ yarn-error.log
 /coverage/
 /dist/
 /docs
+/td*.json
 
 typedoc*.tgz
 tmp

.vscode/launch.json

@@ -6,16 +6,16 @@
     "configurations": [
         {
             "args": [
+                "-r",
+                "ts-node/register",
                 "--timeout",
                 "0",
                 "--config",
-                "${workspaceFolder}/.config/mocha.fast.json",
-                "-g",
-                "2200"
+                "${workspaceFolder}/.config/mocha.fast.json"
             ],
             "internalConsoleOptions": "openOnSessionStart",
             "name": "Debug Tests",
-            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+            "program": "${workspaceFolder}/node_modules/mocha/bin/mocha.js",
             "request": "launch",
             "skipFiles": ["<node_internals>/**"],
             "type": "node"
@@ -24,6 +24,7 @@
             "name": "Attach",
             "port": 9229,
             "request": "attach",
+            "internalConsoleOptions": "openOnSessionStart",
             "skipFiles": ["<node_internals>/**"],
             "type": "node",
             "sourceMaps": true

.vscode/settings.json

@@ -39,5 +39,14 @@
 
     "eslint.workingDirectories": [".", "./example"],
     "mochaExplorer.configFile": ".config/mocha.test-explorer.json",
-    "cSpell.words": ["cname", "tsbuildinfo", "tsdoc"]
+    "cSpell.words": [
+        "cname",
+        "deserializers",
+        "linkcode",
+        "linkplain",
+        "shiki",
+        "tsbuildinfo",
+        "tsdoc",
+        "typestrong"
+    ]
 }

CHANGELOG.md

@@ -1,3 +1,79 @@
+# Beta
+
+### Breaking Changes
+
+-   `@link`, `@linkcode` and `@linkplain` tags will now be resolved with TypeScript's link resolution by default. The `useTsLinkResolution` option
+    can be used to turn this behavior off, but be aware that doing so will mean your links will be resolved differently by editor tooling and TypeDoc.
+-   TypeDoc will no longer automatically load plugins from `node_modules`. Specify the `--plugin` option to indicate which modules should be loaded.
+-   The `packages` entry point strategy will now run TypeDoc in each provided package directory and then merge the results together.
+    The previous `packages` strategy has been preserved under `legacy-packages` and will be removed in 0.25. If the new strategy does not work
+    for your use case, please open an issue.
+-   Removed `--logger` option, to disable all logging, set the `logLevel` option to `none`.
+-   Dropped support for legacy `[[link]]`s, removed deprecated `Reflection.findReflectionByName`.
+-   Added `@overload` to default ignored tags.
+
+### API Breaking Changes
+
+-   The `label` property on `Reflection` has moved to `Comment`.
+-   The default value of the `out` option has been changed from `""` to `"./docs"`, #2195.
+-   Renamed `DeclarationReflection#version` to `DeclarationReflection#projectVersion` to match property on `ProjectReflection`.
+-   Removed unused `Reflection#originalName`.
+-   Removed `Reflection#kindString`, use `ReflectionKind.singularString(reflection.kind)` or `ReflectionKind.pluralString(reflection.kind)` instead.
+-   The `named-tuple-member` and `template-literal` type kind have been replaced with `namedTupleMember` and `templateLiteral`, #2100.
+-   Properties related to rendering are no longer stored on `Reflection`, including `url`, `anchor`, `hasOwnDocument`, and `cssClasses`.
+-   `Application.bootstrap` will no longer load plugins. If you want to load plugins, use `Application.bootstrapWithPlugins` instead, #1635.
+-   The options passed to `Application.bootstrap` will now be applied both before _and_ after reading options files, which may cause a change in configuration
+    if using a custom script to run TypeDoc that includes some options, but other options are set in config files.
+-   Moved `sources` property previously declared on base `Reflection` class to `DeclarationReflection` and `SignatureReflection`.
+-   Moved `relevanceBoost` from `ContainerReflection` to `DeclarationReflection` since setting it on the parent class has no effect.
+-   Removed internal `ReferenceType.getSymbol`, reference types no longer reference the `ts.Symbol` to enable generation from serialized JSON.
+-   `OptionsReader.priority` has been renamed to `OptionsReader.order` to more accurately reflect how it works.
+-   `ReferenceType`s which point to type parameters will now always be intentionally broken since they were never linked and should not be warned about when validating exports.
+-   `ReferenceType`s now longer include an `id` property for their target. They now instead include a `target` property.
+-   Removed `Renderer.addExternalSymbolResolver`, use `Converter.addExternalSymbolResolver` instead.
+-   Removed `CallbackLogger`.
+-   Removed `SerializeEventData` from serialization events.
+-   A `PageEvent` is now required for `getRenderContext`. If caching the context object, `page` must be updated when `getRenderContext` is called.
+-   `PageEvent` no longer includes the `template` property. The `Theme.render` method is now expected to take the template to render the page with as its second argument.
+-   Removed `secondaryNavigation` member on `DefaultThemeRenderContext`.
+-   Renamed `navigation` to `sidebar` on `DefaultThemeRenderContext` and `navigation.begin`/`navigation.end` hooks to `sidebar.begin`/`sidebar.end`.
+
+### Features
+
+-   Added `--useTsLinkResolution` option (on by default) which tells TypeDoc to use TypeScript's `@link` resolution.
+-   Added `--jsDocCompatibility` option (on by default) which controls TypeDoc's automatic detection of code blocks in `@example` and `@default` tags.
+-   Reworked default theme navigation to add support for a page table of contents, #1478, #2189.
+-   Added support for `@interface` on type aliases to tell TypeDoc to convert the fully resolved type as an interface, #1519
+-   Added support for `@namespace` on variable declarations to tell TypeDoc to convert the variable as a namespace, #2055.
+-   Added support for `@prop`/`@property` to specify documentation for a child property of a symbol, intended for use with `@interface`.
+-   TypeDoc will now produce more informative error messages for options which cannot be set from the cli, #2022.
+-   TypeDoc will now attempt to guess what option you may have meant if given an invalid option name.
+-   Plugins may now return a `Promise<void>` from their `load` function, #185.
+-   TypeDoc now supports plugins written with ESM, #1635.
+-   Added `Renderer.preRenderAsyncJobs` and `Renderer.postRenderAsyncJobs`, which may be used by plugins to perform async processing for rendering, #185.
+    Note: Conversion is still intentionally a synchronous process to ensure stability of converted projects between runs.
+-   TypeDoc options may now be set under the `typedocOptions` key in `package.json`, #2112.
+-   Added `--cacheBust` option to tell TypeDoc to include include the generation time in files, #2124.
+-   Added `--excludeReferences` option to tell TypeDoc to omit re-exports of a symbol already included from the documentation.
+-   Introduced new render hooks `pageSidebar.begin` and `pageSidebar.end`.
+
+### Bug Fixes
+
+-   TypeDoc will now ignore package.json files not containing a `name` field, #2190.
+-   Fixed `@inheritDoc` on signatures (functions, methods, constructors, getters, setters) being unable to inherit from a non-signature.
+-   Interfaces/classes created via extending a module will no longer contain variables/functions where the member should have been converted as properties/methods, #2150.
+-   TypeDoc will now ignore a leading `v` in versions, #2212.
+-   Category titles now render with the same format in the page index and heading title, #2196.
+-   Fixed crash when using `typeof` on a reference with type arguments, #2220.
+-   Fixed broken anchor links generated to signatures nested within objects.
+
+### Thanks!
+
+-   @bodil
+-   @futurGH
+-   @jm4rtinez
+-   @muratgozel
+
 # Unreleased
 
 ## v0.23.28 (2023-03-19)

README.md

@@ -19,7 +19,7 @@ npm install typedoc --save-dev
 
 ## Usage
 
-To generate documentation TypeDoc needs to know your project entry point, and TypeScript
+To generate documentation TypeDoc needs to know your project entry point and TypeScript
 compiler options. It will automatically try to find your `tsconfig.json` file, so you can
 just specify the entry point of your library:
 
@@ -38,37 +38,10 @@ By default, TypeDoc will search for a file called `index` under the directory.
 
 ### Monorepos / Workspaces
 
-If your codebase is comprised of one or more npm packages, you can pass the paths to these
-packages and TypeDoc will attempt to determine entry points based on `package.json`'s `main`
-property (with default value `index.js`) and if it wasn't found, based on `types` property.
-If any of the packages given are the root of an [npm Workspace](https://docs.npmjs.com/cli/v7/using-npm/workspaces)
-or a [Yarn Workspace](https://classic.yarnpkg.com/en/docs/workspaces/) TypeDoc will find all
-the `workspaces` defined in the `package.json`. In order to find your entry points, TypeDoc requires
-either that you turn on sourcemaps so that it can discover the original TS file, or that you
-specify `"typedocMain": "src/index.ts"` to explicitly state where the package entry point is.
-Supports wildcard paths in the same fashion as those found in npm or Yarn workspaces.
-
-#### Single npm module
-
-```bash
-typedoc --entryPointStrategy packages .
-```
-
-#### Monorepo with npm/Yarn workspace at the root
-
-```bash
-typedoc --entryPointStrategy packages .
-```
-
-#### Monorepo with manually specified sub-packages to document
-
-This can be useful if you do not want all your workspaces to be processed.
-Accepts the same paths as would go in the `package.json`'s workspaces
-
-```bash
-# Note the single quotes prevent shell wildcard expansion, allowing typedoc to do the expansion
-typedoc --entryPointStrategy packages a-package 'some-more-packages/*' 'some-other-packages/*'
-```
+If your codebase is comprised of one or more npm packages, you can build documentation for each of them individually
+and merge the results together into a single site by setting `entryPointStrategy` to `packages`. In this mode TypeDoc
+requires configuration to be present in each directory to specify the entry points. For an example setup, see
+https://github.com/Gerrit0/typedoc-packages-example
 
 ### Arguments