@apify/docusaurus-plugin-typedoc-api 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Miles Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# docusaurus-plugin-typedoc-api
+
+[![Build Status](https://travis-ci.org/milesj/docusaurus-plugin-typedoc-api.svg?branch=master)](https://travis-ci.org/milesj/docusaurus-plugin-typedoc-api)
+[![npm version](https://badge.fury.io/js/docusaurus-plugin-typedoc-api.svg)](https://www.npmjs.com/package/docusaurus-plugin-typedoc-api)
+[![npm deps](https://david-dm.org/milesj/docusaurus-plugin-typedoc-api.svg?path=packages/plugin)](https://www.npmjs.com/package/docusaurus-plugin-typedoc-api)
+
+A Docusaurus plugin for generating source code `/api/*` routes, powered by
+[TypeDoc](https://typedoc.org/).
+
+The plugin has been designed to document your public API by default (anything exported from a
+package's entry point), so any private, protected, or internal code will not be generated.
+
+## Requirements
+
+- `typescript` >= v4
+- `@docusaurus/core` >= v2.0.0-beta.18
+- `@docusaurus/preset-classic` >= v2.0.0-beta.18
+
+## Examples
+
+- [Boost](https://github.com/milesj/boost) - https://boostlib.dev/api
+
+## Installation
+
+```
+yarn add --dev docusaurus-plugin-typedoc-api
+```
+
+Open your `docusaurus.config.js` and make the following changes:
+
+- Add a link to the API route under `themeConfig.navbar.items` and `themeConfig.footer.links` (if
+  desired).
+
+```js
+module.exports = {
+  // ...
+  themeConfig: {
+    // ...
+    navbar: {
+      // ...
+      items: [
+        // ...
+        {
+          to: 'api',
+          label: 'API',
+          position: 'left',
+        },
+      ],
+    },
+  },
+};
+```
+
+- Configure the plugin in your `plugins` list. The `projectRoot` and `packages` options are
+  required.
+
+```js
+module.exports = {
+  // ...
+  plugins: [
+    [
+      'docusaurus-plugin-typedoc-api',
+      {
+        projectRoot: path.join(__dirname, '..'),
+        // Monorepo
+        packages: ['packages/example', 'packages/other'],
+        // Polyrepo
+        packages: ['.'],
+      },
+    ],
+  ],
+};
+```
+
+## Configuration
+
+The following options are available to the plugin:
+
+- `projectRoot` (`string`) - Absolute path to the project root where `tsconfig.json` is located.
+  _(Required)_
+- `packages` (`(string | PackageConfig)[]`) - List of packages relative to the project root.
+  _(Required)_
+- `banner` (`string`) - Banner message to display at the top of the index page. Supports HTML.
+- `changelogName` (`string`) - Name of the changelog file within a package. Defaults to
+  `CHANGELOG.md`.
+- `changelogs` (`boolean`) - Include and render the changelog file from every package. Defaults to
+  `false`.
+- `exclude` (`string[]`) - List of glob patterns to exclude unwanted packages. This is necessary
+  when using TypeScript project references.
+- `gitRefName` (`string`) - GitHub repository ref name to point the API links to. Defaults to
+  `master`.
+- `minimal` (`boolean`) - Render a minimal layout and reduce the amount of information displayed.
+  Defaults to `false`.
+- `packageJsonName` (`string`) - Name of the `package.json file`. Defaults to `package.json`.
+- `readmeName` (`string`) - Name of the readme file within a package. Defaults to `README.md`.
+- `readmes` (`boolean`) - Include and render the readme file from every package. Defaults to
+  `false`.
+- `removeScopes` (`string[]`) - Package scopes and prefixes to remove when displaying the package
+  name in the sidebar and index. For example, `boost` will remove `@boost/` and `boost-`.
+- `sortPackages` (`(a, d) => number`) - Function to sort the package list in the sidebar and on the
+  index page. Defaults to alphabetical.
+- `sortSidebar` (`(a, d) => number`) - Function to sort the categories and items within each
+  sidebar, excluding "Overview" and "Changelog". Defaults to alphabetical.
+- `tsconfigName` (`string`) - Name of the TypeScript config file in the project root. Defaults to
+  `tsconfig.json`.
+- `typedocOptions` (`object`) - [TypeDoc options](https://typedoc.org/guides/options/#input-options)
+  to pass to the compiler. Only supports a small subset of options, primarily around visibility
+  exclusion.
+
+### Packages
+
+The `packages` option has been designed to support multiple packages, with multiple entry points per
+package. By default the option accepts a list of strings, where each value is a relative path to a
+package folder, and a default entry point of `src/index.ts`.
+
+```js
+module.exports = {
+  packages: ['packages/core', 'packages/react'],
+};
+```
+
+However, an object can be provided to customize the entry point. All entry point file paths are
+relative to the package folder, and support 2 formats:
+
+- **Index imports** - Consumers can only import from the package index. This is typically an entry
+  point like `src/index.ts`.
+- **Deep imports** - Consumers can import anything from the package using its file path. Glob the
+  entire package by only passing the folder name like `src/`. _(This is useful for component
+  libraries)_
+
+```js
+module.exports = {
+  packages: [
+    'packages/core',
+    {
+      path: 'packages/react',
+      // Index only imports allowed
+      // import {} from 'package'
+      entry: 'src/index.tsx',
+      // Deep imports allowed
+      // import {} from 'package/some/nested/file'
+      entry: 'src/',
+    },
+  ],
+};
+```
+
+When _not_ using deep imports, multiple entry points can be defined by passing a map of objects to
+`entry`, where each key is a sub-path that can be imported from the package (excluding the `index`).
+Each entry object requires a `path` and a `label`, which is used for categorizing and sidebars.
+
+```js
+module.exports = {
+  packages: [
+    'packages/core',
+    {
+      path: 'packages/react',
+      entry: {
+        // import {} from 'package'
+        index: 'src/index.tsx',
+        // import {} from 'package/client'
+        client: { file: 'src/client.tsx', label: 'Client' },
+        // import {} from 'package/server'
+        server: { file: 'src/server.tsx', label: 'Server' },
+        // import {} from 'package/server/test'
+        'server/test': { file: 'src/server/test-utils.tsx', label: 'Server test utils' },
+      },
+    },
+  ],
+};
+```
+
+> Index entry points don't require a label, so a file path can be passed directly.
+
+## Linking
+
+This plugin supports API and documentation linking within source code docblocks via the `@apilink`
+and `@doclink` tokens respectively. This works in a similar fashion to
+[TypeDoc's `@link` resolution](https://typedoc.org/guides/link-resolution/), but also supports
+Docusaurus versioning and routing patterns.
+
+### `@apilink`
+
+When linking to other APIs, you must reference them by class name, function name, property, etc,
+_instead of_ the actual `/api` route.
+
+```sh
+# Maps to /api/<package>/class/Registry#register
+{@apilink Registry.register}
+{@apilink Registry.register | Text to use as the label}
+```
+
+### `@doclink`
+
+When linking to documentation pages, you must reference the article by its URL identifier without
+the `/docs` prefix.
+
+```sh
+# Maps to /docs/commands/setup
+{@doclink commands/setup}
+{@doclink commands/setup | Text to use as the label}
+```
+
+## Versioning
+
+This plugin supports API versioning by piggy-backing off the built-in
+[docs versioning implementation](https://docusaurus.io/docs/versioning), which is a _requirement_
+for this to work correctly.
+
+To begin, version your docs with the built-in command:
+
+```shell
+yarn docusaurus docs:version 1.2.3
+```
+
+Once the markdown files are generated, run our versioning command _with the same version used
+previously_:
+
+```shell
+yarn docusaurus api:version 1.2.3
+```
+
+This will create multiple JSON files in the `versioned_docs/version-1.2.3` directory. Be sure to
+commit these files to your repo.
+
+> When versioning, the current state of your branch will be used as that version's API. To
+> update/regenerate old versions, you'll need to checkout an old commit, re-version, and copy the
+> generated files to the latest branch.
+
+### Navigation
+
+Our API is unable to use the
+[`docsVersionDropdown`](https://docusaurus.io/docs/api/themes/configuration#navbar-docs-version-dropdown)
+navigation type, as it's hardcoded in Docusaurus core. However, you can create a custom version
+dropdown like so:
+
+```js
+const versions = require('./versions.json');
+
+module.exports = {
+  // ...
+  themeConfig: {
+    // ...
+    navbar: {
+      // ...
+      items: [
+        // ...
+        {
+          type: 'dropdown',
+          to: 'api',
+          label: 'API',
+          position: 'left',
+          items: [
+            { label: 'Next', to: 'api/next' },
+            ...versions.map((version, i) => ({
+              label: version,
+              to: i === 0 ? 'api' : `api/${version}`,
+            })),
+          ],
+        },
+      ],
+    },
+  },
+};
+```
+
+> This workaround isn't perfect and may be buggy. Use at your own risk!
+
+### Caveats
+
+- Each version in `versioned_docs` (or `versions.json`) _must_ contain the generated API JSON files,
+  otherwise the build will fail.
+- The header/footer API links are _not_ version aware, as their values are static.
+- We suggest only versioning major versions, as the size of these JSON files and the webpack build
+  will get very large very fast.
+
+## Comparison
+
+There's another plugin called
+[docusaurus-plugin-typedoc](https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc),
+that offers a similar solution. However, there are many differences between that package and this
+one, with the biggest being that theirs generates markdown files and `/docs/api/...` styled routes,
+while ours renders custom React pages with `/api/...` styled routes. Some other differences are:
+
+- An index of all packages.
+- Readme inclusion and rendering.
+- Custom styles, sections, and headings.
+- Multiple function and method signatures.
+- [Versioning](#versioning)!
+- And probably more....

package/assets/styles-8ad572ec.css

@@ -0,0 +1,303 @@
+:root {
+	--tsd-muted-text: var(--ifm-color-secondary-darkest);
+	--tsd-font-small: var(--ifm-h6-font-size);
+	--tsd-spacing-vertical: 0.75rem;
+	--tsd-spacing-vertical-full: 2rem;
+	--tsd-spacing-horizontal: 1rem;
+}
+
+.tsd-panel {
+	border: 1px solid var(--ifm-card-background-color);
+	border-radius: var(--ifm-global-radius);
+	margin-bottom: var(--ifm-spacing-vertical);
+	overflow: hidden;
+}
+
+.tsd-panel > .tsd-panel {
+	margin: var(--tsd-spacing-horizontal);
+}
+
+.tsd-panel-header {
+	background-color: var(--ifm-card-background-color);
+	padding: var(--tsd-spacing-vertical) var(--tsd-spacing-horizontal);
+	margin: 0;
+	position: relative;
+}
+
+.tsd-panel-content {
+	margin: 0;
+	padding: var(--tsd-spacing-vertical) var(--tsd-spacing-horizontal);
+	border-bottom: 1px solid var(--ifm-card-background-color);
+}
+
+.tsd-panel-content:empty {
+	display: none;
+}
+
+.tsd-panel-content:last-child {
+	border-bottom: 0;
+}
+
+.tsd-panel-content > *:first-child {
+	margin-top: 0;
+}
+
+.tsd-panel-group,
+.tsd-footer {
+	margin-top: var(--tsd-spacing-vertical-full);
+}
+
+.tsd-panel-header .tsd-anchor {
+	margin-left: 0.5rem;
+	float: right;
+}
+
+.tsd-panel-header .tsd-anchor-id {
+	position: absolute;
+	top: -4.5rem;
+	right: 0;
+}
+
+.tsd-divider {
+	margin: var(--tsd-spacing-vertical) -1rem;
+	border: 1px solid var(--ifm-card-background-color);
+	border-bottom: 0;
+}
+
+.tsd-header-flags {
+	float: right;
+}
+
+.tsd-header-member-fullname {
+	display: inline-block;
+	margin-top: -1rem;
+	margin-bottom: 1.5rem;
+}
+
+.tsd-footer {
+	text-align: center;
+}
+
+html[data-theme='light'] .tsd-panel-header {
+	background-color: var(--ifm-hover-overlay);
+}
+
+html[data-theme='light'] .tsd-panel,
+html[data-theme='light'] .tsd-panel-content {
+	border-color: var(--ifm-hover-overlay);
+}
+
+/* LISTS */
+
+.tsd-hierarchy,
+.tsd-type-parameters {
+	list-style: square;
+	margin: 0;
+}
+
+.tsd-index-list,
+.tsd-signatures,
+.tsd-descriptions,
+.tsd-sources ul,
+.tsd-sources p {
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.tsd-index-list {
+	display: flex;
+	flex-wrap: wrap;
+}
+
+.tsd-index-list li {
+	width: 100%;
+	padding-right: 1rem;
+}
+
+@media screen and (min-width: 576px) {
+	.tsd-index-list li {
+		width: 50%;
+	}
+}
+
+@media screen and (min-width: 997px) {
+	.tsd-index-list li {
+		width: 33%;
+	}
+}
+
+/* SPACING */
+
+.tsd-parameters h5,
+.tsd-type-parameters-title,
+.tsd-parameters-title,
+.tsd-returns-title {
+	margin: 0;
+}
+
+.tsd-comment,
+.tsd-comment > .markdown,
+.tsd-sources,
+.tsd-descriptions,
+.tsd-type-declaration,
+.tsd-type-parameters,
+.tsd-parameters {
+	margin-top: var(--tsd-spacing-vertical);
+	margin-bottom: 0;
+}
+
+.tsd-comment-root {
+	margin-top: 0;
+	margin-bottom: var(--tsd-spacing-vertical-full);
+}
+
+/* SOURCES */
+
+.tsd-sources,
+.tsd-footer {
+	color: var(--tsd-muted-text);
+	font-size: var(--tsd-font-small);
+}
+
+.tsd-sources ul,
+.tsd-sources p {
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.tsd-footer a,
+.tsd-sources a {
+	color: var(--tsd-muted-text);
+	text-decoration: underline;
+}
+
+.tsd-footer a:hover,
+.tsd-sources a:hover {
+	color: var(--ifm-link-color);
+}
+
+/* SIGNATURES */
+
+.tsd-description > *,
+.tsd-parameters {
+	margin-top: var(--tsd-spacing-vertical);
+}
+
+.tsd-description > *:first-child {
+	margin-top: 0;
+}
+
+.tsd-signature-inactive {
+	opacity: 0.35;
+}
+
+.tsd-signature-default-value {
+	margin-left: 0.2rem;
+}
+
+/* FLAGS */
+
+.tsd-flag-group:first-child {
+	margin-right: 0.5rem;
+}
+
+.tsd-flag-group:last-child {
+	margin-left: 0.5rem;
+}
+
+.tsd-flag {
+	display: inline-block;
+	padding: 3px 6px;
+	border-radius: var(--ifm-global-radius);
+	color: var(--ifm-footer-title-color);
+	background-color: var(--ifm-footer-background-color);
+	text-indent: 0;
+	font-size: var(--tsd-font-small);
+	font-weight: normal;
+	margin-top: -1px;
+	opacity: 0.65;
+	vertical-align: middle;
+}
+
+.tsd-flag:not(:first-child) {
+	margin-left: 0.25rem;
+}
+
+/* MODIFIERS */
+
+.badge-group {
+	font-size: var(--tsd-font-small);
+	vertical-align: middle;
+}
+
+.tsd-panel-header .badge-group {
+	display: inline-block;
+	margin-left: 0.25em;
+}
+
+.badge-group > span {
+	margin-right: 0.25rem;
+}
+
+/* SYNTAX */
+
+.tsd-generics {
+	font-weight: normal;
+}
+
+.tsd-signature-symbol,
+.tsd-signature-type-generic {
+	color: var(--tsd-muted-text);
+	font-weight: normal;
+}
+
+.tsd-signature-type {
+	font-style: italic;
+	font-weight: normal;
+}
+
+.tsd-pressable {
+	cursor: pointer;
+}
+
+.tsd-kind-icon .codicon {
+	margin-right: 0.5rem;
+}
+
+.codicon[class*='codicon-'] {
+	vertical-align: middle;
+	display: inline-block;
+}
+
+/*
+	This is copied from Docusaurus:
+	https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-theme-classic/src/theme/DocItem/styles.module.css#L19
+*/
+
+@media only screen and (min-width: 997px) {
+	.apiItemCol {
+		max-width: 75% !important;
+	}
+
+	/* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
+	.apiTocMobile {
+		display: none;
+	}
+}
+
+/* DOCUSAURUS */
+
+.tsd-kind-icon {
+	word-break: break-all;
+}
+
+.apiPage .menu__link:not(.menu__link--sublist),
+.apiPage .table-of-contents__link,
+.tsd-truncate {
+	display: block;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}

package/lib/components/AnchorLink.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const React = require('react');
+const _interopDefault = e => e && e.__esModule ? e : {
+  default: e
+};
+const React__default = /*#__PURE__*/_interopDefault(React);
+function AnchorLink({
+  id
+}) {
+  return /*#__PURE__*/React__default.default.createElement("a", {
+    className: "tsd-anchor",
+    href: `#${id}`
+  }, /*#__PURE__*/React__default.default.createElement("span", {
+    className: "tsd-anchor-id",
+    id: id
+  }), /*#__PURE__*/React__default.default.createElement("i", {
+    className: "codicon codicon-symbol-numeric"
+  }));
+}
+exports.AnchorLink = AnchorLink;
+//# sourceMappingURL=AnchorLink.js.map

package/lib/components/AnchorLink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnchorLink.js","sources":["../../src/components/AnchorLink.tsx"],"sourcesContent":null,"names":["React"],"mappings":";;;;;;;;AACO,SAAS,UAAU,CAAC;AAC3B,EAAE,EAAE;AACJ,CAAC,EAAE;AACH,EAAE,oBAAoBA,sBAAK,CAAC,aAAa,CAAC,GAAG,EAAE;AAC/C,IAAI,SAAS,EAAE,YAAY;AAC3B,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,GAAG,eAAeA,sBAAK,CAAC,aAAa,CAAC,MAAM,EAAE;AAC9C,IAAI,SAAS,EAAE,eAAe;AAC9B,IAAI,EAAE,EAAE,EAAE;AACV,GAAG,CAAC,eAAeA,sBAAK,CAAC,aAAa,CAAC,GAAG,EAAE;AAC5C,IAAI,SAAS,EAAE,gCAAgC;AAC/C,GAAG,CAAC,CAAC,CAAC;AACN;;;;"}

package/lib/components/ApiChangelog.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const React = require('react');
+const themeCommon = require('@docusaurus/theme-common');
+const ApiItemLayout = require('./ApiItemLayout.js');
+const _interopDefault = e => e && e.__esModule ? e : {
+  default: e
+};
+const React__default = /*#__PURE__*/_interopDefault(React);
+const emptyToc = [];
+function ApiChangelog({
+  changelog: Changelog,
+  route
+}) {
+  return /*#__PURE__*/React__default.default.createElement(ApiItemLayout, {
+    heading: "Changelog",
+    pageMetadata: /*#__PURE__*/React__default.default.createElement(themeCommon.PageMetadata, {
+      description: Changelog.contentTitle,
+      title: "Changelog | API"
+    }),
+    route: route,
+    toc: Changelog.toc ?? emptyToc
+  }, /*#__PURE__*/React__default.default.createElement("section", {
+    className: "tsd-readme"
+  }, /*#__PURE__*/React__default.default.createElement(Changelog, null)));
+}
+module.exports = ApiChangelog;
+//# sourceMappingURL=ApiChangelog.js.map

package/lib/components/ApiChangelog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiChangelog.js","sources":["../../src/components/ApiChangelog.tsx"],"sourcesContent":null,"names":["React","PageMetadata"],"mappings":";;;;;;;;;;AAGA,MAAM,QAAQ,GAAG,EAAE,CAAC;AACL,SAAS,YAAY,CAAC;AACrC,EAAE,SAAS,EAAE,SAAS;AACtB,EAAE,KAAK;AACP,CAAC,EAAE;AACH,EAAE,oBAAoBA,sBAAK,CAAC,aAAa,CAAC,aAAa,EAAE;AACzD,IAAI,OAAO,EAAE,WAAW;AACxB,IAAI,YAAY,eAAeA,sBAAK,CAAC,aAAa,CAACC,wBAAY,EAAE;AACjE,MAAM,WAAW,EAAE,SAAS,CAAC,YAAY;AACzC,MAAM,KAAK,EAAE,iBAAiB;AAC9B,KAAK,CAAC;AACN,IAAI,KAAK,EAAE,KAAK;AAChB,IAAI,GAAG,EAAE,SAAS,CAAC,GAAG,IAAI,QAAQ;AAClC,GAAG,eAAeD,sBAAK,CAAC,aAAa,CAAC,SAAS,EAAE;AACjD,IAAI,SAAS,EAAE,YAAY;AAC3B,GAAG,eAAeA,sBAAK,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AACzD;;;;"}

package/lib/components/ApiDataContext.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const React = require('react');
+const ApiDataContext = /*#__PURE__*/React.createContext({
+  options: {
+    banner: '',
+    breadcrumbs: true,
+    gitRefName: 'master',
+    minimal: false,
+    pluginId: 'default',
+    scopes: []
+  },
+  reflections: {}
+});
+exports.ApiDataContext = ApiDataContext;
+//# sourceMappingURL=ApiDataContext.js.map

package/lib/components/ApiDataContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiDataContext.js","sources":["../../src/components/ApiDataContext.ts"],"sourcesContent":null,"names":["createContext"],"mappings":";;;;AACY,MAAC,cAAc,gBAAgBA,mBAAa,CAAC;AACzD,EAAE,OAAO,EAAE;AACX,IAAI,MAAM,EAAE,EAAE;AACd,IAAI,WAAW,EAAE,IAAI;AACrB,IAAI,UAAU,EAAE,QAAQ;AACxB,IAAI,OAAO,EAAE,KAAK;AAClB,IAAI,QAAQ,EAAE,SAAS;AACvB,IAAI,MAAM,EAAE,EAAE;AACd,GAAG;AACH,EAAE,WAAW,EAAE,EAAE;AACjB,CAAC;;;;"}