Out-of-the-box usable documentation generator

[thufschmitt]

Is your feature request related to a problem? Please describe.

I'd like to publish some autogenerated documentation for Organist. nickel doc gives me two choices:

• Export to Markdown. But the Markdown output is only part of the job for a good documentation page, and it's broken;
• Export to JSON. This is strictly more powerful than Markdown, but also requires a lot of work to be turned into a good documentation website.

This is a shame because https://nickel-lang.org/stdlib/std has a pretty decent documentation generator, just not packaged in a generic fashion.

Describe the solution you'd like

Extract the doc generator embedded in https://github.com/tweag/nickel-lang.org to make it usable by any Nickel project. Or provide any other good documentation generator that can spit out html.

Describe alternatives you've considered

• Implement it myself. I have a PoC here that together with pandoc and https://codeberg.org/thufschmitt/pandoc-tree-sitter-filter can output the skeleton of something like that. But it's far from being even remotely nice
• Don't display the code documentation and instead rely on the LSP for that. That could be viable since the LSP is pretty good, but it would be a bit sad

Additional context
Add any other context or screenshots about the feature request here.

[yannham]

Export to Markdown. But the Markdown output is only part of the job for a good documentation page, and it's broken;

In which way is it broken? Is it something worth opening an issue for, that we can fix independently from this issue?

[thufschmitt]

Is it something worth opening an issue for

Indeed, I should have started with that :)

I've just opened #1706 for it

[yannham]

@thufschmitt now that #1706 has been closed, do you still think it would be desirable to have a bespoke documentation generator, or that markdown+pandoc (or whtaever) is sufficient for your purpose?

[thufschmitt]

I think a bespoke doc generator is still needed. Going from Markdown to something like https://nickel-lang.org/stdlib/std is still a huge step

That being said, it might be something that would be better done outside of Nickel itself, as a standalone doc-json -> fancy html converter