feature request: easy static site generation from deno_doc

[izelnakri]

Hi there, I wasn't sure where to post this feature request after checking bunch of places, so I'm posting here hope its not the wrong location 😅

As a user I would like to generate a graphviz .DOT graph and maybe output it to a .dot or .html file of JS/TS dependencies given a file or source code. I think this would be a great documentation tool. In node.js userland I found bunch of projects but best ones are not mature/being developed. I think this would be best achieved in the deno cli itself, or maybe an offical and optional tool that could be exposed under deno when installed lazily on prompt.

Examples:

deno graph module_a.ts # outputs .dot representation to stdout

deno graph module_a.ts -o module_a.svg

deno graph module_a.ts -c config.json

deno graph src # outputs .dot representation of all .ts files to stdout

deno graph src -o mylibrary.svg

deno graph src/**/*-test.ts -o test_dependency_graph.svg

[kitsonk]

We already have deno info --json module_a.ts as well as deno_graph which is a JavaScript interface to the Rust APIs.

Outside of supporting a specific 3rd party library, how would this be an improvement?

[izelnakri]

The benefit would be to show the dependency graph in a visual way in addition to existing ways, resulting in shorter time to understand a package/dependency, analyse and teach it.

We declare quite a bit information when we are authoring a file with dependency imports and types, however existing tools today are still limited. Causing libraries being kept at minimum documentation and introducing extra time and mental costs for learning.

https://doc.deno.land/ was a good move as in what could be visually displayed & share, inspired by docs.rs and other types of tools however it should also be run locally and offline. A similar and much simpler UI could be built just for dependency graphs, web server can also serve these links as svgs etc if needed for further documentation & offline/online reference use.

[kitsonk]

The benefit would be to show the dependency graph in a visual way in addition to existing ways,

Well deno info without JSON does that. One visual way is debatable over another.

Taking the output of the --json and transforming it into a .dot file or using deno_graph to do the same sounds like a great community project.

There are already a few community projects that provide graph visualisation capabilities. Notably Deno Visualizer by @danopia.

[izelnakri]

I see deno CLI interface also as a development kit. Deno relies on URLs to fetch dependencies, many people will rely on url documentations to view a release before reading its multi-file code base. So officially committing to default offline tool could be very useful for the ecosystem & if migration from node to deno is desirable. I understand that such feature introduces baggage, however I think benefits to deno exceed its costs.

Thanks for also referring to Deno Visualizer, I'll check to see how difficult is it to run it offline/as a cli tool. Basically I am arguing that this feature and type documentation would be useful. On node.js side I am already using typedoc to generate type documentation in html or md formats. Example: https://memoria.surge.sh/classes/model_src.Model.html#find . I'm not sure how the standard json I generate from typedoc works with the json deno doc --json generates. Having one tool that does all html and other offline file format documentation generation could be useful for the node/deno DX parity.

[kitsonk]

I see deno CLI interface also as a development kit.

It is, and it comes with minimalistic but extensible tools to a) print a module graph (deno info), b) export a module graph (deno info --json), c) generate documentation (deno doc), d) export documentation (deno doc --json). When those are insufficient or you want runtime access to those same API, deno_graph and deno_doc are available, along with deno_cache which provides runtime API access to the DENO_DIR.

docland is the repository which powers doc.deno.land and uses deno_doc and deno_graph to do that. It runs under Deno Deploy in production, but also runs perfectly well under Deno CLI. Everything is server side rendered as single standalone files with no client side JavaScript. If someone wanted to contribute an "offline mode"/static generator for the docs, that should be quite easy to accomplish and the contribution would be welcome.

[danopia]

Thanks for also referring to Deno Visualizer, I'll check to see how difficult is it to run it offline/as a cli tool.

Fortunately you're not the first to have wanted this, so:

$ deno install -f -n deno-graph --allow-run=deno,dot https://raw.githubusercontent.com/cloudydeno/module-visualizer/main/feat/dependencies-of/cli.ts
✅ Successfully installed deno-graph

$ deno-graph https://deno.land/x/djwt@v2.4/mod.ts
digraph "imported modules" {
  rankdir="TB";

  "https://deno.land/x/djwt@v2.4"[shape="box",label="/x/djwt@v2.4\l4 files, 9 KB\l",penwidth="1.6931471805599454",fontname="Arial",style="filled",tooltip="https://deno.land/x/djwt@v2.4",fillcolor="lightskyblue",href="https://deno.land/x/djwt@v2.4"];
  "https://deno.land/x/djwt@v2.4" -> "https://deno.land/std@0.105.0";

  "https://deno.land/std@0.105.0"[shape="box",label="/std@0.105.0\l    • /encoding\l2 files, 3 KB\l",penwidth="1",fontname="Arial",style="filled",tooltip="https://deno.land/std@0.105.0",fillcolor="lightgreen",href="https://deno.land/std@0.105.0"];

}

My dot text is definitely not intended to be user facing though :D If you have graphviz installed then it can be rendered too: deno-graph https://deno.land/x/djwt@v2.4/mod.ts -o graph.png. There's also a dot link on the website which shows you the raw text online.

Also note that "Module Visualizer" is intentionally focused on viewing a higher-level graph of modules, e.g. which dependencies have nodes in the tree (vs. which actual files Deno has loaded). This differs from deno info's output and I'm not sure which are you are looking for.

[kitsonk]

I knew summoning @danopia was a good idea! 😁

[izelnakri]

Thank you for your inputs!

@danopia I was indeed looking for a cli tool like this. I've run through your example it works for higher-level external dependency graph as a summary. It is also nice that it has the size and the amount of files group under a node.

Also note that "Module Visualizer" is intentionally focused on viewing a higher-level graph of modules, e.g. which dependencies have nodes in the tree (vs. which actual files Deno has loaded)

Pretty soon after I realized this indeed doesn't show internal file based dependency graph which I was expecting as a default. It would be great if I could get internal dependency graph as well, in other words providing a file path instead of a folder path should yield file based graph instead of module based graph:

sh deno-graph ./test/module_a.ts

File has internal module dependencies but only shows a single node when there is no external dependency, which means it doesn't give much information. Current output:

digraph "imported modules" {
  rankdir="TB";

  "file://"[shape="box",label="file://\l2 files, 673 B\l",penwidth="1",fontname="Arial",style="filled",tooltip="file://"];

}

Currently cli always outputs a single node for the project module(internal dependency tree). A better default in this case could be to make this show the actual internal and external dependency tree. Additional flag could be provided to specify the depth of grouping of external and/or internal modules.

$ deno-graph test/some_module.ts # shows all files in the graph(including files in external dependencies)
$ deno-graph test/some_module.ts group-by=module # external dependency origin summary + file graph for internal files
$ deno-graph test/some_module.ts group-by=origin  # current behavior: group by external dependencies, and a single node for the internal.

@kitsonk I'll check to see if I can build the html https://doc.deno.land/ generates offline easily, last year when I checked this was not possible, certain code was not public if I remember correctly. Making this more accessible through a cli would indeed be very useful I think, not only this would make more people use the type documentation, it can also allow for more configuration possibilities in the future like themes or html content customization.

[kitsonk]

I have changed the title of this to better reflect what is being requested, which is easy static site generation of documentation from deno_doc, or integrated into deno_doc.

[crowlKats]

Closing this as it has been achieved!