Mirror of forum.nim-lang.org

3999 :: Does `nim doc` generate any RST at any stage by chance?

• JohnAD (orginal) [2018-06-30T01:11:12+02:00] view original

  I have about four more libraries coming out soon. (And corresponding videos.)

  So, I'm wanting to create for myself a "best practice" for writing books and/or docs with as much efficiency as possible. To that end, I'm doing the following to get some of the RST files from Nim's built in doc service:

  
  #!/bin/bash
  nim doc src/example.nim
  pandoc --from=html --to=rst --output=docs/example.rst example.html
  rm example.html
  Run

  Pandoc does convert the html to RST. But it isn't pretty as the HTML has lots of trappings that don't convert well to RST. The irony, of course, is that the Nim is getting the ## comments in source in the RST format in the first place, then generating the HTML.

  Before I go coding my own solution; I thought I'd ask: is there a known utility that does what I'm looking for in a better way?

  (In case anyone asks: going from RST source to epub, mobi, Amazon self-pub, readthedocs.org, etc is far easier than from HTML. HTML is great, but it makes far too many styling decisions.)

  If nothing else, I'll probably use nim jsondoc to get something more parsable and roll my own solution. But I wanted to ask first.

---

• kaushalmodi (orginal) [2018-06-30T04:27:01+02:00] view original

  Couldn't render post #24881.

---

• JohnAD (orginal) [2018-06-30T19:56:52+02:00] view original

  Yes, getting non-html documentation for the module is the goal. Just thinking out loud... the solution could:

  1. return an RST of the whole module documentation. This could then be embedded into whatever the programmer wanted. Essentially nim doc <target> except into RST rather than html.
  2. return a JSON or YAML containing the documentation. Essentially the same as nim jsondoc <target> except that:

  1. the description fields are not converted to html
  2. (bonus) it also parses the main documentation not associated with a type/method/etc, perhaps an entry of type "main".

  3. be a library. Essentially, the same as #2 except it leaves the result in memory as a json doc not an output file.

  I've already got so many projects in progress already. But perhaps I could add just one more...

---

• JohnAD (orginal) [2018-06-30T20:01:46+02:00] view original

  If I were to write this myself. I'd probably make it a crude text parser. While parsing the code tree like a compiler would be a fascinating challenge; life is too short. It would not be perfect.

---