Karel
Karel10mo ago

Module documentation preview in development

I am trying to improve development experience when documenting Deno modules. What I would like to achieve ideally is to have a real-time preview of a module documentation close to what is generated on deno.land/x so that I can make sure that the documentation for my modules is spot on. Is there a way to do that? I was experimenting with deno doc command, but it does not support watch mode. I guess that the easiest solution with the current tooling would be to run deno doc --html whenever a code changes, and serve the resulting html using some live-server that would check for changes as well. Not a great solution. Next, I was looking into https://github.com/denoland/docland and use the deno_doc package in combination with Fresh to get automatic refresh of the documentation. I was not able to make this work though since I am using some npm references and the deno_docis not able to load that using the default loader. Does anyone have a better solution how to achieve good DX for documenting code?
GitHub
GitHub - denoland/docland: The documentation generation website for...
The documentation generation website for Deno. Contribute to denoland/docland development by creating an account on GitHub.
2 Replies
ioB
ioB10mo ago
deno doc should definitely support watch mode. I’ll submit a PR for that
Karel
Karel10mo ago
I was able to work around the deno_doc issue by bypassing NPM loading:
import { doc } from "https://deno.land/x/deno_doc@0.86.0/mod.ts";
import { load as defaultLoad } from "https://deno.land/x/deno_graph@0.53.0/loader.ts";

function load(specifier: string) {
if (specifier.startsWith("npm:")) {
return Promise.resolve({
"kind": "external" as const,
"specifier": specifier,
});
}
return defaultLoad(specifier);
}

const docNodes = await doc("file:///C:/Users/Me/Project/mod.ts", { load });
import { doc } from "https://deno.land/x/deno_doc@0.86.0/mod.ts";
import { load as defaultLoad } from "https://deno.land/x/deno_graph@0.53.0/loader.ts";

function load(specifier: string) {
if (specifier.startsWith("npm:")) {
return Promise.resolve({
"kind": "external" as const,
"specifier": specifier,
});
}
return defaultLoad(specifier);
}

const docNodes = await doc("file:///C:/Users/Me/Project/mod.ts", { load });
Not sure if this is the right approach though.