versioned docs for nim and fusion

[timotheecour]

I suggest the following layout for docs:

versioned nim docs

https://nim-lang.github.io/Nim/os.html # already exists, stays valid
https://nim-lang.github.io/Nim/devel/os.html # os.nim in Nim devel
https://nim-lang.github.io/Nim/1.2.6/os.html # os.nim in Nim 1.2.6
https://nim-lang.github.io/Nim/1.2/os.html # os.nim in latest point release in 1.2.x branch (ie 1.2.6 currently)

• (unchanged) doc comments href links (eg as generated by ## * `getProjectPath proc <macros.html#getProjectPath>`_ have the correct semantics, pointing to relative docs, so that this href from https://nim-lang.github.io/Nim/1.2.6/os.html would resolve to https://nim-lang.github.io/Nim/1.2.6/macros.html

note: in this scheme, https://nim-lang.github.io/Nim/lib.html could simply point to docs hosted under https://nim-lang.github.io/Nim/ or use the same versioned scheme (except it'd omit devel docs)

versioned fusion docs

fusion publishes its own docs, and they're similarly versioned, eg:

instead of the current way: https://nim-lang.github.io/fusion/src/fusion/filepermissions.html
do this:

https://nim-lang.github.io/fusion/filepermissions.html
https://nim-lang.github.io/fusion/master/filepermissions.html
https://nim-lang.github.io/fusion/1.6.8/filepermissions.html # for a hypothetical fusion@1.6.8

open question: hierarchical vs flat docs

independently of above, a question is whether to use hierarchical or flat layout; nim doc --project --docroot generates hierarchical layout (eg see https://nim-lang.github.io/fusion/src/fusion/htmlparser/xmltree.html) which is robust against duplicate module names, and also has its advantages

flat layout also has its advantages:

• when files move around (eg refactoring) while maintaining same import semantics (thanks to --path)
• shorter urls, that can be entered without remembering the whole path

I suggest we generate both, which is cheap/easy to do:

• https://nim-lang.github.io/fusion/master/fusion/htmlparser/xmltree.html
• https://nim-lang.github.io/fusion/master/xmltree.html

and use the convention that doc comments use the flat layout for simplicity, eg: ## * `foo proc <foo.html#foo>`_, this can be done by making sure docgen does the right thing when interpreting such links so they'll work with both hierarchical and flat layout

theindex.html

one question is whether API symbols from fusion appear in nim's theindex.html (and dochacks search box suggestion). We could generate both:

• theindex.html: a joined index (nim's stdlib + fusion at hash bundled with nim)
• std_theindex.html: only stdlib symbols
  note that fusion_theindex.html would not be needed, it'd be under https://nim-lang.github.io/fusion/theindex.html
• future work can add a search box (by improving dochacks.nim) that would allow github-like search to narrow your search

nim doc --project should support a "flat layout" option

this would simplify generating docs in a flat layout, using a single nim doc invocation (refs nim-lang/Nim#14376 which we probably should re-open)

links

• https://github.com/nim-lang/fusion/pull/56/files#r546163434

[nc-x]

Versioned docs confuse google leading to it showing old results (which was (still is?) a big problem with the rust docs). I would prefer the online docs to always be the latest, and those who are on some old version can use the docs bundled with it (idk if currently they are bundled or not).

[Araq]

The docs are versionized but we don't expose the links because of Google, as you mentioned.

[timotheecour]

Noindex should work, see https://developers.google.com/search/reference/robots_meta_tag

[github-actions]

This RFC is stale because it has been open for 1095 days with no activity. Contribute a fix or comment on the issue, or it will be closed in 30 days.