allow a flat hierarchy for docs

[timotheecour]

note:

its' a common requested feature:

• nim doc recursive should allow specifying a directory and flattened structure nim-lang/Nim#14376

Put all the docs in a target directory (using a flattened hierarchy)

• nim doc --project shows '@@/' instead of '../' for relative paths to submodules nim-lang/Nim#14448

[preferred] Get rid of the relative paths altogether

• nim doc recursive should allow specifying a directory and flattened structure nim-lang/Nim#14376 nim doc recursive should allow specifying a directory and flattened structure · Issue #14376 · nim-lang/Nim

Providing the options to:
Put all the docs in a target directory (using a flattened hierarchy)

• nim doc --project broken with imports below main project file or duplicate names nim-lang/Nim#13150
  (my original suggestion before we settled on nim doc --project broken with imports below main project file or duplicate names nim-lang/Nim#13150 (comment))

the most robust solution is to flatten the hierarchy in exactly the same way as done for nim c
perhaps the particular mangling scheme can be adapted for urls but idea is identical.

proposal: --docroot:@flat

I think this option would make a lot of sense to add, it'd basically force a flat hierarchy; since it's incompatible with any other choice for --docroot, it avoids any conflicting option.
Whether that'd be default or not depends on convincing araq (refs: nim-lang#13150 (comment))
but we can still fake relative paths in what's shown in html (if needed).
I think that'd work great for monorepos (ie, with multiple nimble packages) such as nim (which holds compiler, stdlib, tools etc); you'd have 1 dir per nimble project, each with it's own theindex.html, and everything would be flat wrt to their nimble project eg:

compiler/theindex.html # the index just for compiler
compiler/ast.html # for compiler/ast.nim
compiler/itersgen.html # instead of compiler/plugins/itersgen.html
...
std/theindex.html
std/sytem.html
std/set.html # instead of lib/pure/collections/sets.html

name clashes do occur

stdlib is careful about avoiding those (lib/system/sets.nim is include and doesn't clash with lib/pure/collections/sets.nim, ditto with atomics and alloc) but it may not be desirable in other projects; or even in collections of files for which you want to generate docs;
for eg:

there are 46 names clashes within $nim/tests (eg: tests/misc/tcast.nim clash tests/destructor/tcast.nim); sure it's not a real nimble package, but it could make sense to create docs for those (eg to link to additional tests for a given module or concept); treating is dir as a separate package would be overkill, and wouldn't work well because of cross references (eg foo importing sub/bar)

resolving name clashes with flat hierarchy

we can use any reasonable mangling scheme, but it will "leak" in the hrefs so it shouldn't be ugly

• eg1: use what's used for nimcache but adapted for urls (see my suggestion in nim doc --project broken with imports below main project file or duplicate names nim-lang/Nim#13150 (comment))
  mypkg/bar # => mypkg/bar.html
  mypkg/foo/bar # => mypkg/foo@bar.html
  mypkg/foo/sub/bar # => mypkg@foo@sub@bar.html #
  mypkg/../other1/bar # => mypkg@@other1@bar.html # outside import
  mypkg/../../other2/bar # => mypkg@@@@other2@bar.html # outside import

• eg2: use shortest unique suffix path:
  mypkg/bar # => mypkg/bar.html
  mypkg/foo/bar # => mypkg/foo@bar.html
  mypkg/foo/sub/bar # => mypkg/sub@bar.html # instead of mypkg/foo/sub/bar.html
  mypkg/../foo/bar # => mypkg@@foo@bar.html # outside import

that's a practical choice; it works well with --path semantics

external hrefs

another issue to consider is if an href is created for mypkg/foo.html, the external links to it are created; then later mypkg/other/foo.nim is added; this will either invalidate mypkg/foo.html or cause it to point to wrong file depending on mangling scheme used. We can handle all this well with docgen to guarantee all internal links are correct; but for external href's it's harder.

note:

doesn't close it because --docroot:@flat is IMO a good idea that we should do, and its' a common requested feature to:

• nim doc recursive should allow specifying a directory and flattened structure nim-lang/Nim#14376

Put all the docs in a target directory (using a flattened hierarchy)

• nim doc --project shows '@@/' instead of '../' for relative paths to submodules nim-lang/Nim#14448

[preferred] Get rid of the relative paths altogether

links

nim-lang#14448 (comment)