Projects: tune examples on project creation

[agjohnson]

The project example configuration in the project creation wizard will eventually need some tuning:

• [x] Examples should avoid distracting users and aim solely to onboard users to a working build. Right now we have some notes on more advanced usage (alternative build tools you can use, optional configuration attributes) that will direct the users towards being distracted.
• [ ] Show more granular tool options options
  • "Sphinx with OpenAPI" for example -- these options can give us a chance to illustrate how to use multiple build tools together, instead of showing python/ruby/etc build tool versions on all examples.
• [ ] Perhaps figure out how to display complex configuration examples, that require more than just a RTD config. This is still most likely to be links out to documentation though.
• [x] Make it clear that the user needs to manually add the file. It's not clear from this UI and sometimes other VCS backed services will commit files for users -- CircleCI had an option for this and I just did this with Crowdin.

[humitos]

Right now we have some notes on more advanced usage (alternative build tools you can use, optional configuration attributes) that will direct the users towards being distracted.

Good point. This was useful before because we only had just one example 👍🏼

Perhaps figure out how to display complex configuration examples, that require more than just a RTD config. This is still most likely to be links out to documentation though.

Yes, my plan for this was to add a link to a specific page in our docs that explains how to integrate the addons, for example. Basically, pointing to the pages written in https://github.com/readthedocs/readthedocs.org/issues/11187

[agjohnson]

Also just noticed that the UI doesn't quite imply that the user needs to do this manually. While setting up Crowdin the other day, their configuration file was commit to the repo for me. Users might expect our UX is similar.

I would probably replace the existing note:

It should explicitly give directions "Save and commit the following example configuration to your repository root as .readthedocs.yaml." instead. I'd not use another paragraph on this page, there is a lot of text distracting the user already.

We might be able to make this a link into GitHub's file editor and commit changes UI, I don't know about other providers support for this though.

[humitos]

While setting up Crowdin the other day, their configuration file was commit to the repo for me.

CircleCI also does this when setting up a new project. We talked about this in the past and we agreed on being too complex for us and also it would require asking for write permissions in the repository which is something we don't want.

[agjohnson]

I wasn't suggesting we commit the configuration file, that is indeed way too complex.

Users might be expecting our UX is the same as other services though, we don't mention on that UI what they need to do with the example configuration. I could see how users would feel like we're going to do something automatically for the user.