TypeDoc integration & docs (#33)

* 0.1.1 * Export LogCollector type * Add types & dependencies for link maps * Richer representation of link maps * Proof of concept link mapping works * Docs for the TypeDoc integration * Doc fixes * Update lockfiles
irskep · Sep 2, 2024 · 2382701 · 2382701
1 parent f4e49d4
commit 2382701
Show file tree

Hide file tree

Showing 19 changed files with 469 additions and 3,351 deletions.
diff --git a/Makefile b/Makefile
@@ -11,6 +11,9 @@ client: templates/html/static/client.js
 typedoc:
 	bunx typedoc 
 
+typedoc-linkmap:
+	bunx linkmapper-typedoc docs/src/types.json docs/src/typescript_link_mapping.json
+
 docs: templates/html/static/client.js
 	bun --bun src/cli.ts docs --local
 

diff --git a/bun.lockb b/bun.lockb
diff --git a/docs/djockey.yaml b/docs/djockey.yaml
@@ -10,6 +10,10 @@ project_info:
   version: 0.1.1
   github_url: https://github.com/irskep/djockey
 
+link_mappings:
+  - path: src/typescript_link_mapping.json
+    url_root: api/
+
 gfm:
   ignore_static:
     ["**/*.css", "**/*.js", "**/*.html", "**/api/assets/**/*", "**/types.json"]

diff --git a/docs/src/changelog.dj b/docs/src/changelog.dj
@@ -4,6 +4,10 @@ order: -1
 
 # Changelog
 
+## 0.2 (unreleased)
+
+- [Typedoc integration](#typedoc-integration)
+
 ## 0.1
 
 ### 0.1.1 - 2024-08-30

diff --git a/docs/src/features/typedoc.dj b/docs/src/features/typedoc.dj
@@ -0,0 +1,55 @@
+{#typedoc-integration}
+# Typedoc integration
+
+{added-in-version="0.2"}
+:::
+:::
+
+{tag=aside .caution}
+:::
+TypeDoc integration hasn't been tested broadly. Please [create an issue on GitHub](https://github.com/irskep/djockey/issues/new) if you run into any trouble.
+:::
+
+Djockey can integrate with [TypeDoc](https://typedoc.org) to create an integrated documentation experience that combines the authoring power of Djockey with rich API references. For example, here in the Djockey docs, we can type `[](:ts:DjockeyPlugin)`{.language-djot} and get [](:ts:DjockeyPlugin).
+
+The core concept is to render TypeDoc normally inside your docs directory, treat its output as static files, and then create convenient link aliases into it.
+
+## 1. Run TypeDoc
+
+First, run TypeDoc on your project with JSON and HTML output. The JSON output can go anywhere, but the HTML must go inside your docs source directory next to your markup.
+
+```sh
+npx typedoc src/index.ts \
+  --json docs/src/types.json \
+  --out docs/src/api
+```
+
+## 2. Generate a link map
+
+Djockey uses a _link map file_ to figure out where to point links to. You generate a link map using a separate program called `linkmapper-typedoc`.
+
+```sh
+npm install --dev @djockey/linkmapper-typedoc
+npx linkmapper-typedoc \
+  docs/src/types.json \
+  docs/src/typescript_link_map.json
+```
+
+## 3. Configure Djockey
+
+Assuming your `djockey.yaml` is under `docs`...
+
+{filename="docs/djockey.yaml"}
+```yaml
+link_mappings:
+  - path: src/typescript_link_map.json
+    url_root: api/
+```
+
+The path is relative to `djockey.yaml`{.language-sh}. `url_root` should be the place you rendered TypeDoc's HTML output to.
+
+## 4. Link to your API docs
+
+From here, you can write `:ts:symbolName` as a link destination to get a link into your TypeDoc API reference. If you need to disambiguate, for example to refer to a method on a specific class, you can add parent types like `:ts:SomeClass.someMethod` or `:ts:namespace.SomeClass.someMethod`.
+
+If your link doesn't have any text, the text will be populated automatically. So you can say `[API reference for DjockeyPlugin](:ts:DjockeyPlugin)`{.language-djot} to customize the link text, or just `[](:ts:DjockeyPlugin)`{.language-djot} to use the symbol name.
diff --git a/docs/src/features/version_directives.dj b/docs/src/features/version_directives.dj
@@ -40,4 +40,8 @@ Output:
 {added-in-version="10.0"}
 :::
 We're really excited about this feature!
-:::
+:::
+
+## Other options
+
+You can also use `changed-in-version`, `removed-in-version`, and `deprecated-in-version`.
diff --git a/docs/src/typescript_link_mapping.json b/docs/src/typescript_link_mapping.json
@@ -0,0 +1,265 @@
+{
+  "version": 0,
+  "namespaces": [
+    "typescript",
+    "ts",
+    "typedoc"
+  ],
+  "linkMappings": [
+    {
+      "linkDestination": "DocSet",
+      "relativeURL": "classes/DocSet.html",
+      "defaultLabel": "DocSet"
+    },
+    {
+      "linkDestination": "DocSet.constructor",
+      "relativeURL": "classes/DocSet.html#constructor",
+      "defaultLabel": "constructor"
+    },
+    {
+      "linkDestination": "DocSet.config",
+      "relativeURL": "classes/DocSet.html#config",
+      "defaultLabel": "config"
+    },
+    {
+      "linkDestination": "config",
+      "relativeURL": "classes/DocSet.html#config",
+      "defaultLabel": "config"
+    },
+    {
+      "linkDestination": "DocSet.docs",
+      "relativeURL": "classes/DocSet.html#docs",
+      "defaultLabel": "docs"
+    },
+    {
+      "linkDestination": "docs",
+      "relativeURL": "classes/DocSet.html#docs",
+      "defaultLabel": "docs"
+    },
+    {
+      "linkDestination": "DocSet.plugins",
+      "relativeURL": "classes/DocSet.html#plugins",
+      "defaultLabel": "plugins"
+    },
+    {
+      "linkDestination": "plugins",
+      "relativeURL": "classes/DocSet.html#plugins",
+      "defaultLabel": "plugins"
+    },
+    {
+      "linkDestination": "DocSet.tree",
+      "relativeURL": "classes/DocSet.html#tree",
+      "defaultLabel": "tree"
+    },
+    {
+      "linkDestination": "tree",
+      "relativeURL": "classes/DocSet.html#tree",
+      "defaultLabel": "tree"
+    },
+    {
+      "linkDestination": "DocSet.getDoc",
+      "relativeURL": "classes/DocSet.html#getDoc",
+      "defaultLabel": "getDoc"
+    },
+    {
+      "linkDestination": "getDoc",
+      "relativeURL": "classes/DocSet.html#getDoc",
+      "defaultLabel": "getDoc"
+    },
+    {
+      "linkDestination": "DocSet.makeRenderableCopy",
+      "relativeURL": "classes/DocSet.html#makeRenderableCopy",
+      "defaultLabel": "makeRenderableCopy"
+    },
+    {
+      "linkDestination": "makeRenderableCopy",
+      "relativeURL": "classes/DocSet.html#makeRenderableCopy",
+      "defaultLabel": "makeRenderableCopy"
+    },
+    {
+      "linkDestination": "DocSet.runPasses",
+      "relativeURL": "classes/DocSet.html#runPasses",
+      "defaultLabel": "runPasses"
+    },
+    {
+      "linkDestination": "runPasses",
+      "relativeURL": "classes/DocSet.html#runPasses",
+      "defaultLabel": "runPasses"
+    },
+    {
+      "linkDestination": "LogCollector",
+      "relativeURL": "classes/LogCollector.html",
+      "defaultLabel": "LogCollector"
+    },
+    {
+      "linkDestination": "LogCollector.constructor",
+      "relativeURL": "classes/LogCollector.html#constructor",
+      "defaultLabel": "constructor"
+    },
+    {
+      "linkDestination": "LogCollector.label",
+      "relativeURL": "classes/LogCollector.html#label",
+      "defaultLabel": "label"
+    },
+    {
+      "linkDestination": "label",
+      "relativeURL": "classes/LogCollector.html#label",
+      "defaultLabel": "label"
+    },
+    {
+      "linkDestination": "LogCollector.lines",
+      "relativeURL": "classes/LogCollector.html#lines",
+      "defaultLabel": "lines"
+    },
+    {
+      "linkDestination": "lines",
+      "relativeURL": "classes/LogCollector.html#lines",
+      "defaultLabel": "lines"
+    },
+    {
+      "linkDestination": "LogCollector.loader",
+      "relativeURL": "classes/LogCollector.html#loader",
+      "defaultLabel": "loader"
+    },
+    {
+      "linkDestination": "loader",
+      "relativeURL": "classes/LogCollector.html#loader",
+      "defaultLabel": "loader"
+    },
+    {
+      "linkDestination": "LogCollector.debug",
+      "relativeURL": "classes/LogCollector.html#debug",
+      "defaultLabel": "debug"
+    },
+    {
+      "linkDestination": "debug",
+      "relativeURL": "classes/LogCollector.html#debug",
+      "defaultLabel": "debug"
+    },
+    {
+      "linkDestination": "LogCollector.dump",
+      "relativeURL": "classes/LogCollector.html#dump",
+      "defaultLabel": "dump"
+    },
+    {
+      "linkDestination": "dump",
+      "relativeURL": "classes/LogCollector.html#dump",
+      "defaultLabel": "dump"
+    },
+    {
+      "linkDestination": "LogCollector.error",
+      "relativeURL": "classes/LogCollector.html#error",
+      "defaultLabel": "error"
+    },
+    {
+      "linkDestination": "error",
+      "relativeURL": "classes/LogCollector.html#error",
+      "defaultLabel": "error"
+    },
+    {
+      "linkDestination": "LogCollector.fail",
+      "relativeURL": "classes/LogCollector.html#fail",
+      "defaultLabel": "fail"
+    },
+    {
+      "linkDestination": "fail",
+      "relativeURL": "classes/LogCollector.html#fail",
+      "defaultLabel": "fail"
+    },
+    {
+      "linkDestination": "LogCollector.info",
+      "relativeURL": "classes/LogCollector.html#info",
+      "defaultLabel": "info"
+    },
+    {
+      "linkDestination": "info",
+      "relativeURL": "classes/LogCollector.html#info",
+      "defaultLabel": "info"
+    },
+    {
+      "linkDestination": "LogCollector.succeed",
+      "relativeURL": "classes/LogCollector.html#succeed",
+      "defaultLabel": "succeed"
+    },
+    {
+      "linkDestination": "succeed",
+      "relativeURL": "classes/LogCollector.html#succeed",
+      "defaultLabel": "succeed"
+    },
+    {
+      "linkDestination": "LogCollector.warning",
+      "relativeURL": "classes/LogCollector.html#warning",
+      "defaultLabel": "warning"
+    },
+    {
+      "linkDestination": "warning",
+      "relativeURL": "classes/LogCollector.html#warning",
+      "defaultLabel": "warning"
+    },
+    {
+      "linkDestination": "DjockeyConfig",
+      "relativeURL": "types/DjockeyConfig.html",
+      "defaultLabel": "DjockeyConfig"
+    },
+    {
+      "linkDestination": "DjockeyConfigResolved",
+      "relativeURL": "types/DjockeyConfigResolved.html",
+      "defaultLabel": "DjockeyConfigResolved"
+    },
+    {
+      "linkDestination": "DjockeyDoc",
+      "relativeURL": "types/DjockeyDoc.html",
+      "defaultLabel": "DjockeyDoc"
+    },
+    {
+      "linkDestination": "DjockeyInputFormat",
+      "relativeURL": "types/DjockeyInputFormat.html",
+      "defaultLabel": "DjockeyInputFormat"
+    },
+    {
+      "linkDestination": "DjockeyLinkMapping",
+      "relativeURL": "types/DjockeyLinkMapping.html",
+      "defaultLabel": "DjockeyLinkMapping"
+    },
+    {
+      "linkDestination": "DjockeyLinkMappingDoc",
+      "relativeURL": "types/DjockeyLinkMappingDoc.html",
+      "defaultLabel": "DjockeyLinkMappingDoc"
+    },
+    {
+      "linkDestination": "DjockeyOutputFormat",
+      "relativeURL": "types/DjockeyOutputFormat.html",
+      "defaultLabel": "DjockeyOutputFormat"
+    },
+    {
+      "linkDestination": "DjockeyPlugin",
+      "relativeURL": "types/DjockeyPlugin.html",
+      "defaultLabel": "DjockeyPlugin"
+    },
+    {
+      "linkDestination": "DjockeyPluginModule",
+      "relativeURL": "types/DjockeyPluginModule.html",
+      "defaultLabel": "DjockeyPluginModule"
+    },
+    {
+      "linkDestination": "DjockeyRenderer",
+      "relativeURL": "types/DjockeyRenderer.html",
+      "defaultLabel": "DjockeyRenderer"
+    },
+    {
+      "linkDestination": "DocTree",
+      "relativeURL": "types/DocTree.html",
+      "defaultLabel": "DocTree"
+    },
+    {
+      "linkDestination": "DocTreeSection",
+      "relativeURL": "types/DocTreeSection.html",
+      "defaultLabel": "DocTreeSection"
+    },
+    {
+      "linkDestination": "applyFilter",
+      "relativeURL": "functions/applyFilter.html",
+      "defaultLabel": "applyFilter"
+    }
+  ]
+}