Open timotheecour opened 3 years ago
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).
The docs are versionized but we don't expose the links because of Google, as you mentioned.
Noindex should work, see https://developers.google.com/search/reference/robots_meta_tag
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.
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)
## * `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.htmlnote: 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 advantagesflat layout also has its advantages:
--path
)I suggest we generate both, which is cheap/easy to do:
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 layouttheindex.html
one question is whether API symbols from fusion appear in nim's theindex.html (and dochacks search box suggestion). We could generate both:
nim doc --project
should support a "flat layout" optionthis would simplify generating docs in a flat layout, using a single
nim doc
invocation (refs https://github.com/nim-lang/Nim/issues/14376 which we probably should re-open)links