[docs] rust-toolchain file content

[drmason13]

Problem
The section on rust-toolchain file doesn't say how to simply pick a channel using the file.

I found that simply the word nightly would work where the more verbose content:

[toolchain]
channel = "nightly"

did not work

Steps

1. cargo new foo
2. cd foo and create a file named rust-toolchain with the verbose content:

[toolchain]
channel = "nightly"

3. rustup show

Possible Solution(s)
Update the documentation with an example of using a channel name with no TOML markup

Using a channel (stable, beta or nightly) in a repository can be achieved by setting the content of rust-toolchain to the name of the channel, without any additional TOML markup:
e.g. to use the latest nightly channel, rust-toolchain should only contain:

nightly

Notes

Output of rustup --version:

rustup 1.22.1 (b01adbbc3 2020-07-08)

Output of rustup show:

Default host: x86_64-pc-windows-msvc
rustup home:  C:\Users\masond\.rustup

(error: invalid channel name '[toolchain]' in '\\?\C:\Users\masond\code\rust\foo\rust-toolchain', invalid toolchain name: '[toolchain]')

Output of rustup update:

info: syncing channel updates for 'stable-x86_64-pc-windows-msvc'
info: syncing channel updates for 'nightly-x86_64-pc-windows-msvc'
info: checking for self-updates

   stable-x86_64-pc-windows-msvc unchanged - rustc 1.46.0 (04488afe3 2020-08-24)        
  nightly-x86_64-pc-windows-msvc unchanged - rustc 1.48.0-nightly (d006f5734 2020-08-28)

[rbtcollins]

The new toml syntax isn't released yet. Documentation for the stable release of rustup is here - https://github.com/rust-lang/rustup/tree/stable#the-toolchain-file

[ehuss]

Ah, sorry, it didn't really register in my brain that the TOML syntax hadn't been released yet.

@rbtcollins Is there a timeframe for the next release? Do you have a preference how documentation is published moving forward? I can switch it to only publish during a stable release, so that unreleased changes aren't shown to users. The only downside is that any fixes or updates to older content have to wait, but I think that should probably be ok.

[kinnison]

@ehuss We don't have a timeframe, though I think sooner might be more sensible than later given this kind of issue may otherwise crop up again.

I'd prefer, as I said when we first discussed splitting the docs like this, that over-all I'd want the docs published from stable not from master so if you have time to drop a PR to complete that, then I'd appreciate it.

[ehuss]

Yep, posted #2478.