$ deno docs --local to render the website locally for a local folder/modules

[izelnakri]

Current deno docs only works for published native/3rd modules on https://doc.deno.land/ . We see the CLI response/stdout but would like to have a local version running and publishable privately as well.

I know this is not an easy feat because that website doc generation is run by vercel/npm so I suggest the following path to have this feature as soon as possible. I think it is necessary for rapid adoption considering what deno lacks in the ecosystem compared to node.js/npm:

Suggested strategy for faster release/smoother evolution:

1- Release a sepate cli tool to generate deno docs --local, maybe call it deno-docs or typedocs something like that. That way we dont need to reimplement all the vercel functionality in deno immediately given missing core libraries like React etc in deno.

2- Once assetMap becomes stable and there is a npm migration path to deno, migrate the existing vercel setup deno via deno docs command or we can have the vercel layer completely rewritten in deno.

With this 2 step strategy we can immediately release this feature to devs without needing to wait for a deno specific solution, given problem domain/projects & dependencies are complex on doc generation side.

[lucacasonato]

@izelnakri We want to eventually move HTML generation to Rust. Also it would be totally doable to move the doc website to use Deno. See https://github.com/lucacasonato/dext.ts

[izelnakri]

Great, loved it. Well done!

How early do you think we can have local builds to view offline or to push them to cdn for others to see?

I think documentation could be a significant motivation for people to move to deno.

As soon as we have this feature, I'll port some of my libraries. Really happy with momentum deno has at the moment, lets hype it more ;) Next I'll have suggestions on the testing side after this.

[andykais]

I think the cli interface might be more appropriate like this:

deno docs script.ts --html

similar to the --json output, except it outputs a single fat html page with all the documentation/styles present

[izelnakri]

I agree --html better than --local, there should be support for both folders and single/multiple provided files

[izelnakri]

@ry @lucacasonato Hi there, sorry for posting again but after many deno releases I still dont see any support or news for this feature. I think this is an essential feature that blocks deno's adoption, when I build a library I would like to see the documentation locally-first just like it is in other programming languages & environments, denos great hosted documentation service should be just an option given we have a way to import from any URL we want.

Could we prioritize this feature? What can I do to steer the planning and development?

I don't mean to criticize the current docs service, its amazing with its rust-like type linking & browsing experience. I just want to this also happen locally and locally-first so developers can have more control over releases, develop with documentation-first and customize their library docs if needed.

[kitsonk]

Deno is an open source project and this feature suggestion is a non-trival amount of work. While the docs API could certainly use some love, it currently is not a priority for any of the core developers, which means it really needs someone in the community to be passionate about it.

The core teams current DX focus is to get the language server better.

Also, note that this suggestion has only one upvote. While it isn't critical or a popularity contents the core team does try to pick features and suggestions that have broad community support, and sadly these feature does not at the moment.

[jaydenseric]

It would be awesome if there was a Deno equivalent of jsdoc-md, ideally out of the box.

The whole point of readme files is to document what the software is and how it's used. IMO separate doc sites are inferior to a generated "API" section of the markdown readme, derived from source JSDoc.

• As a user I love it when all the documentation is contained in the readme, and I can use normal github branches/tags to view documentation for particular versions of the software.
• As an author/maintainer I love not having to manage doc site domains and deployments, and readme API doc changes can easily be reviewed in PRs to the actual software, checked in CI (via jsdoc-md --check).

Here is an example of a generated readme "API" section:

https://github.com/jaydenseric/graphql-upload#api

Edit a year later: I no longer think detailed readme API docs are the future, although I still don't think individual projects should setup documentation sites either. Readmes should document the publicly exported modules that users can import, but online web apps like https://doc.deno.land that analyse TypeScript JSDoc for given JavaScript module ULRs on the fly and present rich and even interactive documentation is the future.

[soundstep]

I was also looking at a feature to generate a html doc output.
How can deno doc --json be consumed with minimal effort as of today?

[kitsonk]

It is likely you would want to do something like denoland/docland. It in theory should be easy to adapt to generate static HTML output. Adapting docland to generate static HTML would likely be a welcome contribution.

[tgreen7]

Any updates on this? Has anyone figured out an easy way to consume the json to be used by a markdown/html website?

[kitsonk]

In the past 9 days there have been no contributions.

[Higgs1]

I am currently looking for a static documentation generator for JavaScript. This would be a much welcome addition. I agree that it would be a huge boon for the deno / JavaScript community. Has there been any update on this?