Enhance configuration documentation for version/channel

[calebcartwright]

Refs #4128 (comment) and #4128 (comment)

The configuration options for rustfmt are defined within this repo in Configurations.md and are also available on GH pages

However, these configuration option listings are reflective of the latest configuration settings within source control on the master branch. As such this can drift from the options available in released versions of rustfmt which has understandably been a source of confusion for users.

We should enhance the public documentation of rustfmt configuration options to take version and channel/distribution into account so that users will be able to determine the true set of config options available for the version of rustfmt they are using.

[ayazhafiz]

One way to do this would be to backfill an added-on-version attribute to each config option, similar to rustc's since. Then new config options always take on the version of the next planned release (the problem here is a release must be committed to or some cleanup work should be done before a release). With this information we could parse the configuration readme into several files, perhaps one per minor version and channel (stable/beta for stable features, nightly for all), which get put on GH pages. Readers of the config readme still get told whether a feature is stable and what version it was introduced in, which should be enough information for determining whether the feature is available.

@calebcartwright what do you think?

It would also be nice if we could get rustdoc/docs.rs to do a lot of this work, but I don't think that's possible without exposing other library information.

[calebcartwright]

Thanks for digging into it @ayazhafiz! I haven't really had a chance to think through implementation, but I see two use cases for users that want info about rustfmt config

1. I'm using version X of rustfmt, what config options are available for me with version X (holistic view)
2. For a given config option Y, when was it introduced/stabilized/deprecated (single-config view)

IMHO the former is the most pressing need, as the absence of this capability has been a source of frustration and confusion for users. I think one simple approach that would help in the short term while we consider more strategic options would be to point users (either via instructions or links) to leverage the GH tags to view the corresponding Configurations.md version.

For example:

• rustfmt 2.0 Configuration options - https://github.com/rust-lang/rustfmt/blob/master/Configurations.md
• rustfmt 1.4.15 Configuration options - https://github.com/rust-lang/rustfmt/blob/v1.4.15/Configurations.md
• ....
• rustfmt 1.4.2 Configuration - options https://github.com/rust-lang/rustfmt/blob/v1.4.2/Configurations.md

We could plug those in as links in the main Configurations file in source so folks could see them going forward within the repo and on GH pages.

I'm open to anything that helps users get a clearer picture of the available rustfmt configuration options, but we should also be mindful about the overhead both for contributors and maintainers with whatever solution we end up implementing.

[ayazhafiz]

I like this idea. Looks like the github page takes a tagged version of the config file to render

rustfmt/docs/index.html

Line 69 in e254753

const ConfigurationMdUrl = 'https://raw.githubusercontent.com/rust-lang/rustfmt/master/Configurations.md';

so adding a dropdown (or similar) to change the version should be straightforward. Also looks like gh page has a toggle for stable/all features, but it doesn't seem to work correctly (at least on my firefox)

[calebcartwright]

I really like the solution we've implemented, and it feels like it's covered the major use case that motivated this issue. I've got a couple other smaller feature requests/nice-to-haves, but will open up separate issues for those.