Crystal: Option for the doc command to generate JSON.

[keplersj]

Refs rrrene/inch#38.
/cc @rrrene

[rrrene]

Hi there,

so the idea is to generate JSON as an option so tools can consume it.

What I would love to see is a JSON dump of every code object (class, module, method, constant, etc.) that was identified. For each of these code objects it would be great to see things like name, type, comment, possibly parameters etc.

If there is anything else I could do to help, just let me know! :+1:

[asterite]

That's exactly the idea :-)

We should define the output format. Ideally it should provide all the information that the current crystal docs show, only in JSON format. This could also be used to generate ctags and other things... and probably to do a docs viewer entirely made by using this JSON output (much lightweight, and probably faster, than the current way of generating static content).

If anyone wants to do this, let me know. The code for crystal doc is more or less easy/clear (I think), you can start from here: https://github.com/crystal-lang/crystal/blob/efd1598bb0965d12a5d113442d297762b0e534ca/src/compiler/crystal/tools/doc.cr

@fernandes Maybe you are interested in doing this? :-)

[keplersj]

Should the JSON be printed to STDOUT when using -f json?

[rrrene]

Most tools I have encountered handled it this way. I think, unless there are arguments against it, it offers great flexibility as you can pipe that output whereever you want.

But I have to admit I don't know if there are downsides to this on e.g. Windows?

_edit:_ english is hard.

[keplersj]

I wouldn't worry about Windows right now, I think Crystal is still aways away before it'll run on Windows.

[fernandes]

@asterite I'm in! 😎👍

[jhass]

@fernandes please read issue history carefully, see #2777

[fernandes]

@jhass 👍

[asterite]

@fernandes Sorry, I didn't think a PR was going to be made after just a few hours of opening this issue. @keplersj Awesome work!

[straight-shoota]

So there are two outdated PR's in this context: #2777 which adds an additional output type json besides html and #3762 which enhances html output with index files of types and methods in JSON for browser-based search (see #1792)
They both implement JSON serialization though in a different way (#2777 is very basic and uses outdated to_json(io). I think it would make sense to combine these approaches. Basically there are three basic features in this context:

• JSON serialization for documentable AST nodes
• alternative output type json for crystal docs
• enhanced output type html with a json-based index

I am not sure if these should better be addressed in three focused PR's where the first one is obviously a pre-condition for the other two (who are independent of each other).

It is however debatable if the JSON serialization for both use-cases should actually be the same or needs an entirely different implementation. If the index file should only provide search for identifiers (types, constants, method signatures) it only requires a small subset of all available documentation data and would be relatively small in size. If it should also provide full text search, the actual documentation texts need to be present as well, but it is still focused on searchability and needs not be as detailed as for the json output type.

/cc @rosylilly @keplersj

[straight-shoota]

4746 has been merged with JSON output. It puts the JSON output alongside the HTML.

Based on that we could also add a --format json option to the docs generator to generate only JSON data and print it to STDOUT.

[RX14]

A bit hasty on the close button there...

[mniak]

@straight-shoota implemented on PR #6982