Configuration file accepts .yaml or .yml

[adamchainz]

Details

• Read the Docs project URL: n/a
• Build URL (if applicable):
• Read the Docs username (if applicable):

The config file docs say:

The configuration file must be ... named .readthedocs.yaml.

But I've been getting away with a .yml suffix. Docs could say it works with either?

[astrojuanlu]

We want to gently push people towards using .yaml, see discussion at #7460 :) I don't think we'll drop .yml (what's the point?) but not mentioning it in the documentation will nudge folks towards using the "correct" extension I believe.

[adamchainz]

Some kind of mention on that page (v2 config file) would be good. I saw on the config file index page (https://docs.readthedocs.io/en/stable/config-file/index.html), other filenames are mentioned as deprecated.

[agjohnson]

Technically, you can even write JSON if you want, but we file all of these under hidden use cases that we don't really want to introduce and potentially confuse readers. We've discussed this a bit recently and want to instead provide a single, clear direction here for these steps.

[adamchainz]

Sure. But I was confused as I returned to RtD after a year of not touching the config file. I saw "must ... be named" and I thought maybe my file called differently wasn't even being used.

Perhaps tweak the wording like:

Your configuration file should be called .readthedocs.yaml (although there are some other, soft-deprecated names that are currently accepted).

[astrojuanlu]

I think the wording gets too complicated. "Should" invites people to call it... something else? Like .rtd.yaml or something like that.

Again, I think this is a tradeoff between documenting reality (that we accept several filenames) and keeping documentation simple to better serve users (give just one way to call it, so they don't have to make decisions and they align with what we want from them).

[humitos]

I understand that we decided to not update the documentation to mention all the variants (it's a regex actually), so I'm going to close this issue in favor of having the documentation clear and simple.