show top-level import for top-level runnableExamples in generated docs

[timotheecour]

proposal

make docgen automatically add import foo in the generated html for a top-level runnableExamples inside module foo;

in fact this is what is done by the part of docgen that does for running the code, see https://github.com/nim-lang/Nim/pull/17282/files#diff-2471f1aaac2c91ed83e0317b1b0b322fc719a4cb431de811baa8e350dade283fR531, except that:

• unlike what's done in docgen though, it'll need to show a canonical relative path, not an absolute path; this requires fix #16973 ; nim doc now shows correct, canonical import name in title Nim#16999 which I still need to finalize,
• unlike what's done in docgen, we probably only want to show imports for top-level runnableExamples

pros

easier to copy paste and edit, matches what's actually being run

note

to avoid generating too much noise, this proposal only concerns top-level runnableExamples, so that

doAssert toUpperAscii("FooBar!") == "FOOBAR!"

will remain unaffected instead of generating:

import std/strutils
doAssert toUpperAscii("FooBar!") == "FOOBAR!"

which would just obfuscate (a little bit) the code; it should be clear from context that import std/strutils is needed for runnableExamples attached to a symbol.

it's not perfect, because some large but non top-level runnableExamples could benefit from showing such import, but these are rare; eg: https://nim-lang.github.io/Nim/sugar.html#collect.m%2Cuntyped

links

refs nim-lang/Nim#17203 (comment)
refs https://forum.nim-lang.org/t/7622#48410
pr_fix_rfc_17282_runnableExamples_show_import

[Araq]

Ok with me but it's hardly an important thing to have and I'm tired of the race to the bottom. If one reads a module's documentation and cannot imagine how the import statement should look like, one should read a basic tutorial already. There are certain limits to how far one can get in life with maximizing one's laziness.

[timotheecour]

I thought it was obvious too but a few other people complained (see linked threads) so it's best to centralize discussion in 1 place (RFC) instead of scattering it. For me, the main advantage is it helps a little bit copy pasting code into working code.

(In other languages, it can sometimes be a pain to find which headers/modules to include/import for example snippets; having easy to use examples is nice for people less familiar)

[Clyybber]

Alternatively we could also change the doc gen to not insert those import statements automatically for top-level runnableExamples. Then we would be forced to write the import ourselves and might combine it to import std/[x, ...] instead of the docgen generating

import std/x
import std/[x, ...]

, and the chances of double imports ending up in the docs would be reduced.
(and it would be confusing for modules that need to be included and not imported, although these are rare)

In conclusion I think we should have a way to tell top-level runnableExamples to not generate that import, or simply not insert it automatically.