Some of my runnableExamples also has .. code-block:: nim ;P
Actually I changed from when is_main_module: to runnableExamples (for libs), is the correct way.
I think is an awesome feature, because other lang have DocTests or the like (Python, Rust, etc), but the code is on comments, that means you dont have any features of the IDE/Editor you are using, like syntax highlight, etc, is still code on a comment.
isn't the whole point of rst though that it's sufficiently structured to extract detailed code blocks to pass to the compiler? ie if you're not using this feature of rst, it's completely useless compared to markdown which has a much larger developer mindshare.
tbh, I found the runnableExamples distracting to look at - they're syntax colored along with the rest of the actual code and it's hard to know when the example ends and real code begins (indent is not that clear) - they muddle the logic
It also looked hard to surround examples with descriptive text - you have to start a comment block, end it, write a runnableexample, then start a new comment block which seems really ugly..
@juancarlospaco
I think is an awesome feature, because other lang have DocTests or the like (Python, Rust, etc), but the code is on comments, that means you dont have any features of the IDE/Editor you are using, like syntax highlight, etc, is still code on a comment.
True, but this is a shortcoming of the highlighter. Breaking separation of concerns by putting pure doc sample code outside of doc comments which makes it look like regular code is the wrong answer. Searching for runnableExamples in Nim's github project even finds some code where it is used outside of any doc comment context, which means it is silently ignored.
@arnetheduck Some very valid points. Also, runnableExamples just adds the caption Examples: above the code in the generated doc, which I really don't like.
@dom96 Unfortunately, the :test: code block option is only supported by the nim rst2html sub-command, which takes rst input. nim doc doesn't understand it, so it cannot be used in source code comments.
@timothee IMHO nim doc should support a :compile: option for the code-block directive which tries to compile the code block body on the source code level of the entity the comment is for. This should solve the sync problem.
it's hard to know when the example ends and real code begins (indent is not that clear)
Agreed.
To partly mitigate this, I decided that the initial indent of runnableExamples in my code should be 4 spaces instead of two. (I've tried even larger indentations, but it becomes awkward very soon)
See here how it looks like. Syntax highlighting is still distracting, but at least it is somewhat easier to see when the real code begins.
@dom96 Unfortunately, the :test: code block option is only supported by the nim rst2html sub-command, which takes rst input. nim doc doesn't understand it, so it cannot be used in source code comments.
Ahh, so this should be implemented for nim doc too and problem solved.
True, but this is a shortcoming of the highlighter.
Everything is always a "tooling" problem. Can't see if the variable is a let or a var in Python? Make the highlighter detect it, assign-once variables should be green, multiple assignment variables should be blue... Point is, highlighting is complexity tradeoff too and a there is no need to detect and extract code blocks within comments when they are outside of comments.
Breaking separation of concerns by putting pure doc sample code outside of doc comments which makes it look like regular code is the wrong answer.
Ah we play the noun game now. Runnable examples are code and should be written as code, don't separate identical concerns.
Searching for runnableExamples in Nim's github project even finds some code where it is used outside of any doc comment context, which means it is silently ignored.
That's just not true.
Everything is always a "tooling" problem. [...]
If by that you mean that people sometimes tend to conveniently delegate things they don't want to deal with to tooling in a thoughtless way, I agree. I just don't think it's like that in this case.
Ah we play the noun game now. Runnable examples are code and should be written as code, don't separate identical concerns.
My definition of the separate concerns at hand is just different from yours. Mine are "define what a module/proc etc. does" (regular source code) vs. "help people understand what it does" (docs including example code). That's not a noun game, that's a different view. I also like that the Nim project keeps testing code separate, because testing is another separate concern.
Searching for runnableExamples in Nim's github project even finds some code where it is used outside of any doc comment context, which means it is silently ignored.
That's just not true.
OK now I'm confused: found this https://github.com/nim-lang/Nim/blob/3d60f1b0af6fc3d8d9446a87bd26ff054562fa20/tests/generics/t8694.nim which looks like this (excerpt):
when true:
# Error: undeclared identifier: '|'
proc bar[T](t:T): bool =
runnableExamples:
type Foo = int | float
true
echo bar(0)
When int in the type declaration is replaced with nosuchtype, I expect nim doc to throw an error when it tries to compile the runnableExample block, unless it is ignored. But it doesn't. Am I missing something here? Tested with the latest devel, installed with choosenim.
This isn't specific to Nim. Nim's runnableExamples is a close cousin to D's unittest blocks; as in D, unittest blocks are not embedded in documentation even though they end up in documentation and can be run from html. A difference is that unittest block appears right after proc body, rather than right after proc header (which has pros and cons but the self contained aspect of it is nice).
I expect nim doc to throw an error when it tries to compile the runnableExample block, unless it is ignored. But it doesn't. Am I missing something here?
thanks for reporting this; but please report as github issue next time instead of forum to increase change it gets fixed; just sent out https://github.com/nim-lang/Nim/pull/9262 to fix this particular case; the more general case would be to fix https://github.com/nim-lang/Nim/issues/9216 but that's a separate discussion
True, but I expect editor and IDE devs to put in this additional effort anyway: recognizing fenced markup code blocks inside comments will spread because Rust uses it.
Again, runnableExamples are not just documentation. They are also tests. So far nobody argued for putting tests into comments.
@Araq
Again, runnableExamples are not just documentation. They are also tests.
Does that mean there can be testing code in a block named runnable Example s which is run by the documentation generator, but not by the regular testing framework? Testing and doc examples are two different concerns IMHO. The point of compiling and/or running doc code examples should be to validate the examples, not to test the module. The correctness hierarchy should be tests -> code -> examples, not (tests and examples) -> code.
@timothee
This isn't specific to Nim.
The fact that it is linked to a block comment context while technically being code is specific, and that's the part that bothers me.
... in D, unittest blocks are not embedded in documentation even though they end up in documentation and can be run from html.
TBH that sounds like a great solution:
Can't we get something like this? If runnableExamples was renamed to something with test and detached from comments, the only missing part would be validation for actual doc example code, and that would be relatively straight-forward: the doc generator could just compile example code blocks in doc comments at the end of the module/scope. If .. code-block:: nim is too cumbersome to type, the doc generator could learn about fenced code blocks (```-blocks).
thanks for reporting this; but please report as github issue next time ...
I didn't report it as an issue because I wasn't sure it is one or if it's just me not understanding the intended behavior of the code.
... instead of forum to increase change it gets fixed ...
That was not what I wanted, sorry if I made it look like that.
Yeah, well, runnableExamples is exactly what its name says, it's both, it's documentation that is checked. You dislike this conflation, but I like it ...
If "testing" in runnableExamples means "checking doc code examples", I actually like it very much. If it means "running unit tests", and that's how it is understood by some, I don't like it at all.
.... but should be solved by the editor's code-folding capabilities ...
Many other source code aware tools/IDE features will also have to be aware of runnableExamples to be ignored, ignoring comments is something they already know.