JSON output now parses description and moduleDescription as JSON

[PMunch]

This means that the JSON output format can be used to output other document formats like Markdown.

[Araq]

I like it but since it adds yet more code to the Nim compiler, please make nimdoc a tool of its own. nim doc can call nimdoc for backwards compat.

[PMunch]

That would require the separate tool to understand the Nim command line syntax as well though, meaning that e.g. switches would need to be reflected in both places. Is this really the best way? I guess the compiler could only spit out the machine-readable JSON doc format, and then the external tool could translate it to HTML/Latex/whatever. That way the compiler will stay small, the docgen and rstgen parts would be greatly simplified, and the JSON format would be guaranteed to be up-to-date with the latest documentation generation (so we avoid the jsondoc1 -> 2 cleanup I did).

[Araq]

Is this really the best way?

It's what nimsuggest does too.

[timotheecour]

I guess the compiler could only spit out the machine-readable JSON doc format, and then the external tool could translate it to HTML/Latex/whatever.

this is the best way forward and also what I recommended here #14439 (comment) (ignore the 2nd paragraph macros should be powerful enough to enable full reflection and 100% replace docgen, which is a separate topic that I don't want to bring up here)

there are multiple ways to do that, here's one:

• nim jsondoc -o:foo.json [options] main produces foo.json
• nimdoc --mode:html|pdf|latex|tex --outdir:dir foo.json produces actual docs; and running runnableExamples depending on options passed in
• nim doc [options] main calls nim jsondoc and then nimdoc with appropriate options by shelling out, to reproduce pre-existing behavior

=> no code breaks, it'd be a transparent change for users
=> compiler logic is cleansed from RST parsing etc
=> no code duplication either

[PMunch]

Hmm, I think nim jsondoc should run the tests, that way nimdoc doesn't really need to know anything about Nim or how to compile Nim code. It would just be a pure JSON -> output format converter. But otherwise that's exactly what I had in mind.

[timotheecour]

Hmm, I think nim jsondoc should run the tests

fine with that

[narimiran]

This is rebased on the latest devel, with resolved merge conflicts, in PR #15999.

I guess we can continue the discussion there.