Mirror of forum.nim-lang.org

3033 :: Tutorials and documentation for a nim project

• mratsim (orginal) [2017-07-07T19:16:29+02:00] view original

  There has been a few discussions about tools to write documentation and tutorials in the past:

  • Love Nim but ... with a link to a nim to Sphinx extension.
  • Nim documentation - A Gitbook version with this repo

  Was there some initiatives I missed? Both seem unmaintained.

---

• mratsim (orginal) [2017-07-07T19:39:39+02:00] view original

  Bonus question.

  I'm trying to use nim doc but how to make it follows include ?

---

• Araq (orginal) [2017-07-07T20:17:25+02:00] view original

  nim doc2 follows include files and is generally what should be used. I can't answer the other questions, I'm afraid.

---

• euant (orginal) [2017-07-07T23:11:20+02:00] view original

  I am still around and do plan to eventually find time to work further on the GitBook project I started, just been super busy at work for the last several months.

---

• mratsim (orginal) [2017-07-08T09:44:24+02:00] view original

  @euant no worries !

  @Araq I had to update to the latest devel. It didn`t work with my nim install from the middle of May.

  I checked solutions that could be used to upload to Github Pages easily and was recommended Couscous.io.

  Workflow seems to be:

  • Have a directory of Markdown files
  • couscous preview to check rendering on local machine
  • couscous deploy to commit on gh-pages

---

• mratsim (orginal) [2017-07-08T18:11:10+02:00] view original

  I've used Nim's Docgen to generate a tutorial + documentation.

  End result is here which I'm quite happy with for the time invested.

  A few remarks to ease its use:

  • It would be nice to prepend the autogenerated "API" doc with rst tutorials. As a workaround, I include a .nim file full of commentaries
  • I cannot seem to display images this way.
  • See source switch doesn't work.
    • It ignores docSeeSrcUrl. Issue raised. Even if I don't specify it does a wrong link.
    • It seems non-trivial to link against a specific github commit
    • The edit link links to a devel branch (hardcoded).

  I used find+replace to fix "See source issues" but it would be nice if automated.

---