Add JSON export option

[brutella]

I'm looking for a way to generate documentation in JSON format (instead of HTML) so that I can provide inline documentation for an editor. Similar to golang/go#34293

Would this be possible with this library?

[abhinav]

Hello!
I would not be opposed to a -json flag but I'd need to look at the details more to know for sure.
What form of output are you imagining for the JSON?

There's a small detail to be aware of:
doc2go doesn't load the source code of all the matched packages in-memory at the same time (so that generation of ./... doesn't OOM on really really large repositories). I wouldn't want that to change. The JSON format will need to work with that restriction.

[brutella]

I think one json file/output per package containing all of doc.Package would be enough. I don't have any exact JSON schema in mind though.

[abhinav]

Ah, I see. Thinking about this a bit more, I'm not sure that belongs in doc2go.
It's not clear what value it'll add on top of the linked proposal.

[brutella]

The json output in go doc was added back in 2021 and is not merged (yet). That's why I asked to add a similar option to this library.

[abhinav]

I understand. I wonder why it hasn't been merged yet.

Unfortunately, I don't think a -json flag aligns with the goals of doc2go.
The part that doc2go is focused on is generating a static website.
The static website, the cross-linking, the HTML, etc. -- that's the part that doc2go wants to focus on.
A machine-consumable output isn't really my goal here.

A -json flag, if added, wouldn't be for the actual documentation, but about the HTML that was generated: where to find it, what's in it, etc. I don't think that'll match your needs.

FWIW, it's possible to parse Go code comments using the official go/doc package. You can likely use that to write a simple CLI that generates JSON for consumption by your editor.

I'm going to close this issue for now unless I see a real use case for doc2go to support JSON output.
Thanks for your interest!

[brutella]

Thanks for looking into it. It sounds reasonable to use the official go/doc package instead.