Docs: custom domain documentation

[agjohnson]

trafficstars

I went to link a customer to documentation that it seems we lost some documentation on CNAME flattening, ANAME, etc for custom domains. Maybe I'm not recalling correctly though.

Here are some notes and changes we can decide on to help reduce duplication and splitting navigation around our custom domain documentation:

We currently have two pages on custom domains, which feel a bit similar:

• https://docs.readthedocs.io/en/stable/guides/custom-domains.html - Guide content
• https://docs.readthedocs.io/en/stable/custom-domains.html - Feature content

The guide content does a great job of explaining how to manage custom domains, but I found missing:

• [ ] Mention support for apex domain records using CNAME flattening, ANAME records, and the various non-standard platform features registrars have
• [ ] We don't mention CAA that I can find either. This is a relatively obscure debugging task though

The feature description page has some content that sounds more like it should be on the guide page, and it feels like the feature page should more strictly be about what custom domains do for projects and the benefits of custom domains. This page has some content we can move or remove:

• [x] How custom domains work has a lot of content that explains how to set up custom domains
• [x] The graphic maybe doesn't clear up many questions for me, but is also more description of how to set up custom domains instead of how custom domains work
• [x] Considerations for custom domain usage seems like a note that would be better on the managing guide page instead of our feature description page

There is more content here we could add, and moving/removing some of the content above will make the feature description page really short. But, to keep cleanup fast and light, let's consider future additions for the page and work towards that later. Things like: highlight custom domain use and a landing page for multiple projects, describe that authentication works with custom domains, etc.

[humitos]

@agjohnson isn't this issue solved by https://github.com/readthedocs/readthedocs.org/pull/10719?

[agjohnson]

I handled the larger issues in #10719, but we don't mention CNAME flattening/ANAME/etc at all anymore. CAA is probably worth mentioning somewhere as well.