If it can be of help, nim jsondoc foo.nim generates htmldocs/foo.json that can be parsed to generate other formats. Unfortunately the JSON body contains chunks of HTML that would need to be converted.
If you succeed could you please share the manpages?
I've been looking into this as I tried to convert the RST doc scattered in several files into one org-mode doc. I first thought Pandoc was the culprit but then found that the RST syntax requires a blank line between the block declaration and the content like so:
.. code-block:: nim
:test: "nim c $1"
proc yes(question: string): bool =
echo question, " (y/n)" ...
.. code-block:: nim
proc yes(question: string): bool =
echo question, " (y/n)" ...
When those blank lines are missing, the conversion fails, produces garbage and the first indented code block get deleted in the result as it's interpreted as an option to the directive.
I made the following PR https://github.com/nim-lang/Nim/pull/19418 to correct this in the RST docs.
Many are left in the sources.
In matter of sources documentation and literate programming, nothing can beat the org-mode syntax. If the documentation was provided in org, could they be exported, stable, to any other format, (man, info, pdf, html,..) by org itself or with pandoc. The way I organized it, everything in the doc folder ends in one file containing the variety of RST, the manual, the three chapters of the tutorial, everything at hand, with plain text search, indexing, code highlight, runnable examples, no need to mention :test: "nim c $1", and the list could go on. In comparison to RST or MD... well I don't think it even suffers the comparison !
Gosh, even this forum is using RST styling !
I've been looking into this as I tried to convert the RST doc scattered in several files into one org-mode file. I first thought Pandoc was the culprit but then found that the RST syntax requires a blank line between the block declaration and the content like so:
.. code-block:: nim
:test: "nim c $1"
proc yes(question: string): bool =
echo question, " (y/n)" ...
.. code-block:: nim
proc yes(question: string): bool =
echo question, " (y/n)" ...
When those blank lines are missing, the conversion fails, produces garbage and the first indented code block gets deleted in the result as it's interpreted as an option to the directive.
I made the following PR https://github.com/nim-lang/Nim/pull/19418 to correct this in the RST docs. Many are left in the sources, and the convention isn't consistent. Sometimes that space is present, sometimes not.
Araq's answer: "Nim's RST parser handles this correctly, it's an extension to make RST bearable. That external tools have trouble with it doesn't concern... we have other custom extensions too and rely on them."
I think that's wrong. It should at least be addressed in the documentation that nim is using a modified variant of RST, to make it suck less. Besides, there is a world beyond Nim. Now, if the RST standard should be reviewed and pandoc updated is an open question, but I think RST should, in the future, be simply put aside, so that we could move on, forward, to the correct markup language, once, and for all.
In matter of sources documentation and literate programming, nothing can beat the org-mode syntax. Documentation provided in org, can be exported, stable, to any other format, (man, info, pdf, html,..) by org itself or with pandoc. The way I organized it, everything in the doc folder ends in one file containing the variety of RST, the manual, the three chapters of the tutorial, everything at hand, with plain text search, indexing, code highlight, runnable examples, no need to mention :test: "nim c $1", and the list could goes on. Of course, bringing this into Nim will be a lot of work, but it will also open rooms for great improvements, and bring some communities to get together.
Gosh, even this forum is using RST styling !
[2022-02-06 Sun 15:47] Reposted agin, as it would not render anymore as of NimForum 2.2.0 after CVE-2022-23602