fix #16973 ; nim doc now shows correct, canonical import name in title

[timotheecour]

fix #16973

refs #16970 (comment)

It should be obvious, since it's linked as std/sha1 and the other std/ modules don't include this note either. But I can put the note back, if you prefer, though a better solution IMO would be to make nim doc generate std/sha1 as heading.

try it out locally with: ./koch --nim:bin/nim --localdocs:/tmp/d01 docs --doccmd:skip (takes < 30 seconds)

it all seems to work.

examples

future work

• this PR is needed to implement show top-level import for top-level runnableExamples in generated docs RFCs#352 ( i have a branch ready after this PR is merged: pr_fix_rfc_17282_runnableExamples_show_import) => fix https://github.com/nim-lang/RFCs/issues/352: show top-level import for top-level runnableExamples in generated docs #17542
• make --docroot the default now that this works (EDIT: now unrelated to this PR)
• remove std/ prefix from modules in https://nim-lang.github.io/Nim/lib.html since we'd show it in each module's page and it looks weird to have it just for some modules (and breaks alphabetical ordering etc) => remove std/ prefix from doc/lib.rst now that canonical import is shown in module docs #17543

[konsumlamm]

This fixes #16973.

[Araq]

Still a draft?

[timotheecour]

yes, there's 1 remaining problem which has to do with theindex links; I have a fix in the pipeline...

[timotheecour]

@Araq this is ready now (and I have a PR that depends on this to fix nim-lang/RFCs#352)

[konsumlamm]

The modules in packages/docutils still don't show a qualified name, is that intentional? If not, what should the prefix be? std/ or packages/docutils/? Or something else?

[timotheecour]

for reference:

• lib/packages/docutils/docutils.nimble
• lib/packages/docutils/highlite.nim
• https://nim-lang.github.io/Nim/highlite.html

the module title shows as highlite instead of packages/docutils/docutils even though import highlite doesn't work and user needs import packages/docutils/docutils

the problem is that docutils is a nimble package, because of lib/packages/docutils/docutils.nimble

IMO the fix here is to stop pretending it's a nimble package and remove lib/packages/docutils/docutils.nimble

Alternatively, we can make it a proper nimble package that would be nimble-installed by koch, but note that the package structure is incorrect, as it'd (currently) put every top-level file in scope, eg: import highlight whereas we should require import pkg/docutils/highlight or import docutils/highlight

note that the layout of some modules in nim repo should be improved to avoid scope pollution

=> #17544