As a counterpoint to https://forum.nim-lang.org/t/4274:
Just learned about runnableExamples from some pull requests and forum topics - and would like to share several concerns before this proliferates too widely (rationale repeated from above post, for convenience):
One language that does this really well is Rust, see for example this piece for Result: https://doc.rust-lang.org/std/result/index.html https://doc.rust-lang.org/src/core/result.rs.html#11
Several points can be seen there:
All in all, I believe leaving this feature in will be a hindrance for having good documentation in nim, for several reasons:
Nims RST also can chew some Markdown too, just try it.
All Nim code is "real" I guess.
Rust uses "Code on Comments" and often not highlighted, linted, smart autocompleted, etc as actual code. (Yes Ive used some Rust on modern IDE)
You can just write runnableExamples on a separate file and include it.
Rust uses "Code on Comments" and often not highlighted, linted, smart autocompleted, etc as actual code. (Yes Ive used some Rust on modern IDE)
dunno, but vscode supports it generally (https://code.visualstudio.com/docs/editor/intellisense#_customizing-intellisense), as does the fancy web page above that views the documentation - it's certainly not a technical impossibility - worth keeping in mind that documentation is written once, but read over and over again, thus it makes sense to optimize it for the viewer.
You can just write runnableExamples on a separate file and include it.
How does this address the points above? It moves the examples further away from the code being documented, still leaves no control for the author to mix code and comment, and generally just feels.. complicated.
Nims RST also can chew some Markdown too, just try it.
like this link?
or this code block?
Oh, you are just Trollin'
yawns
I like runnableExamples and prefer it over the old code-block comments.
1.
If you dislike having syntax highlighting in examples, I'm sure the editor can be configured to skip it for runnableExamples blocks.
2.
Is it really that bad? This looks fine to me:
proc f* =
## Start of doc
runnableExamples:
doAssert true
## continue
runnableExamples:
doAssert true
## end
The generated docs looks like a mess because of multiple Examples headers, but that could be fixed.
3.
I wish Araq had chosen markdown instead RST, but that ship has sailed.
3. The big difference between RST and Markdown is that the former is structured
If markdown is transformed into clean HTML5 with presentation aspects separated out into a style sheet, the HTML DOM might even be structured enough for documentation processing purposes.
I like the runnableExamples. It's a great feature that probably no other language has.
I wish Araq had chosen markdown instead RST, but that ship has sailed.
I so wish that Markdown was picked instead too. RST is crazily limitations like not allowing nesting of bold inside italics and such.
The Pandoc Markdown flavor is very mature and allows all kinds of structural syntax.
Sorry for necrobumping, just wanted to note that best practices paragraph from contributing guide recommends assert for runnableExamples currently:
An exception to the above rule is runnableExamples and code-block rst blocks intended to be used as runnableExamples, which for brevity use assert instead of doAssert. Note that nim doc -d:danger main won't pass -d:danger to the runnableExamples, but nim doc --doccmd:-d:danger main would, and so would the second example below:
runnableExamples:
doAssert foo() # bad
assert foo() # preferred
Personally, I'm of two minds about runnableExamples. Lower barrier for contributing testing, even interspersed with documentations is better than no tests at all. However, most of @arnetheduck's concerns are valid and I agree with @gemath:
Some testing code is good example code, but not all of it, and vice versa.
For example, threading code is often not completely deterministic, so you jump through hoops to concoct tests based on assertions. Example code, on the other hand, should demonstrate idiomatic style and be plain and ordinary.
runnableExamples got vastly improved after that original thread time ~2018!
I am a strong proponent of using runnableExamples. If you see any issues with it, may be it deserves a new thread.
Few examples of runnableExamples loaded docs written by me:
@exelotl
When viewing docs I would much rather read: > (examples of echo statements)
But those echo docs are hard to maintain; at some point you will end up with mismatching code and echo examples.
doAssert or assert based examples in runnableExamples can also be new-user friendly.. it depends on the style of writing those assertions.
The best part is that to try out a runnableExample, the reader simply needs to import that library, copy/paste that runnableExamples snippet and expect that to Just Work.
runnableExamples got vastly improved after that original thread time ~2018!
With respect to the original points:
Writing a good doc often means interleaving description and code to weave a readable story - did this improve?
Is there any new visual indication where docs / examples end and actual code starts (beyond an indent that looks like any other)?
Which "vast improvements" happened?
But those echo docs are hard to maintain; at some point you will end up with mismatching code and echo examples.
no. how would it get mismatched?
Which "vast improvements" happened?
Bugfixes and tooling improvements.