Karel•10mo 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•10mo ago

deno doc should definitely support watch mode. I’ll submit a PR for that

Karel•10mo 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.