Make current config version more prominent in our docs

[agjohnson]

I was browsing our docs and noticed this page (clicking on "Configuration File" in the TOC):
https://docs.readthedocs.io/en/stable/config-file/index.html

It feels we could guide the user better by replacing this index page with the content from:
https://docs.readthedocs.io/en/stable/config-file/v2.html

The config index page:

• Mentions the file name you should use
• Mentions file names you shouldn't use. This probably should be in advanced usage, or at least somewhere not the first thing users would interact with
• Mentions why you should use a configuration file over our interface. Our stance could be firmer and clearer here. Use the configuration file, full stop.
• Lists version 2 and version 1 configuration file structure. Which one am I supposed to use as a user?

The V2 config file (and I'll touch on the naming convention thing) accomplish:

• Mentions the config file name
• Shows a great example of a documentation file
• Though it's hard to navigate and digest, this file at least describes all of the options right in the same document. All of our options are easy to find.

So, it could make sense to do the following:

• Replace the index.rst with v2.rst docs. That is, when the user clicks on "Configuration File", we give them "Here is our configuration file, and here is how you use it". Don't be impartial about which version to use, or how users interact with project settings, and be clearer about how many versions the user needs to be aware of (1).
• Don't reference this as config file V2, instead it's just our config file. There is an old version you can use but it's not supported. This is to be clear about what version of our config file to use.

Separately, there are some issues with the display of the config file that make it hard for me to find information. I suppose it's rather dense documentation. More frequent examples, or perhaps a custom formatting to config file options would make this easier to scan for information.

[astrojuanlu]

I wholeheartedly agree with this, I have thought about it many times. In particular:

Don't be impartial about which version to use

I'll raise the bar even more: why keep v1 around?

[agjohnson]

That could absolutely be an option, though perhaps it's a bit longer time frame. We could pull usage information on this rather easily as well though, perhaps it's not used much (it probably is).

This might be a good place to lead ahead of feature deprecation though. Soft deprecation might be to stop pointing users to the v1 docs, or at least making them first page prominent. Medium deprecation is maybe notifications through various projects we've discussed recently about notifying users on deprecated features more, and hard deprecation is a build warning/error.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[benjaoming]

Let's make sure that #9921 fixes this. I haven't gone over this issue in relation with the PR, but I think it's likely that it will solve it.

[humitos]

We are deprecating config file v1. I opened an initial work in progress at #10367. Hopefully, once that's merged we won't be mentioning other version than v2.

[benjaoming]

We did some changes in #10416. They address most concerns in this issue, so I think we should close it 👍

It'll get even better when #10367 deletes the perhaps rather confusing v1 reference and really clarifies everywhere that a configuration file is required.