Change mentions of "CNAME" -> custom domain (#4627)

* Change mentions of "CNAME" -> custom domain

Also some related cleanup of copy around the CNAME -> custom domain
changes.

* Fix typo and do Nginx -> nginx

Author: agjohnson

docs/alternate_domains.rst

@@ -11,17 +11,19 @@ Every project has a subdomain that is available to serve its documentation. If y
 .. note:: If you have an old project that has an underscore (_) in the name, it will use a subdomain with a hyphen (-).
           `RFC 1035 <http://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.
 
-CNAME Support
--------------
+Custom Domain Support
+---------------------
 
-If you have your own domain, you can still host with us.
-This requires two steps:
+You can also host your documentation from your own domain by adding a domain to
+your project:
 
-* Add a CNAME record in your DNS that point to our servers `readthedocs.io`
-* Add a Domain object in the **Project Admin > Domains** page for your project.
+* Add a CNAME record in your DNS that points the domain to: ``readthedocs.io``
+* Add a project domain in the :guilabel:`Domains` project admin page for your project.
 
-.. note:: The ``Domain`` that should be used is the actual subdomain that you want your docs served on.
-          Generally it will be `docs.projectname.org`.
+.. note::
+    We don't currently support pointing subdomains or naked domains to a project
+    using ``A`` records. It's best to point a subdomain, ``docs.example.com``
+    for example, using a CNAME record.
 
 Using pip as an example, https://pip.pypa.io resolves, but is hosted on our infrastructure.
 
@@ -32,23 +34,16 @@ As another example, fabric's dig record looks like this::
     ;; ANSWER SECTION:
     docs.fabfile.org.   7200    IN  CNAME   readthedocs.io.
 
-.. note::
-
-    We used to map your projects documentation from the subdomain that you pointed your CNAME to.
-    This wasn't workable at scale,
-    and now we require you to set the domain you want to resolve on your project.
-
-
-CNAME SSL
----------
+Custom Domain SSL
+-----------------
 
 By default, when you setup a custom domain to host documentation at Read the Docs,
 we will attempt to provision a domain validated SSL certificate for the domain.
 This service is generously provided by Cloudflare.
 
 After configuring your custom domain on Read the Docs,
-you can see the status of the certificate on the domain edit screen
-(**Project Admin > Domains > Edit Domain**).
+you can see the status of the certificate on the domain page in your project
+admin dashboard (:guilabel:`Domains` > :guilabel:`Edit Domain`).
 
 If your domain has configured CAA records, please do not forget to include
 Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
@@ -60,9 +55,11 @@ FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification
     or another variation. While these continue to resolve,
     they do not yet allow us to acquire SSL certificates for those domains.
     Point the CNAME to ``readthedocs.io`` and re-request a certificate
-    by saving the domain (**Project Admin > Domains > Edit Domain**).
+    by saving the domain in the project admin (:guilabel:`Domains` >
+    :guilabel:`Edit Domain`).
 
-    If you change the CNAME, the SSL certificate issuance can take about one hour.
+    If you change the CNAME record, the SSL certificate issuance can take about
+    one hour.
 
 .. important::
 

docs/faq.rst

@@ -112,24 +112,24 @@ Deleting a stale or broken build environment
 
 See :doc:`guides/wipe-environment`.
 
-How do I host multiple projects on one CNAME?
----------------------------------------------
+How do I host multiple projects on one custom domain?
+-----------------------------------------------------
 
-We support the concept of Subprojects.
-If you add a subproject to a project,
-that documentation will also be served under the parent project's subdomain.
+We support the concept of subprojects, which allows multiple projects to share a
+single domain. If you add a subproject to a project, that documentation will
+be served under the parent project's subdomain or custom domain.
 
 For example,
 Kombu is a subproject of Celery,
 so you can access it on the `celery.readthedocs.io` domain:
 
 http://celery.readthedocs.io/projects/kombu/en/latest/
 
-This also works the same for CNAMEs:
+This also works the same for custom domains:
 
 http://docs.celeryproject.org/projects/kombu/en/latest/
 
-You can add subprojects in the Admin section for your project.
+You can add subprojects in the project admin dashboard.
 
 Where do I need to put my docs for RTD to find it?
 --------------------------------------------------

docs/features.rst

@@ -65,4 +65,5 @@ We provide full-text search across all of the pages of documentation hosted on o
 Alternate Domains
 -----------------
 
-We provide support for CNAMEs, subdomains, and a shorturl for your project as well. This is outlined in the :doc:`alternate_domains` section.
+We provide support for custom domains, subdomains, and a shorturl for your
+project as well. This is outlined in the :doc:`alternate_domains` section.

docs/localization.rst

@@ -48,7 +48,10 @@ It also gets included in the Read the Docs flyout:
 
 .. image:: /img/translation_bar.png
 
-.. note:: The default language of any CNAME will be the language of the project the Domain object was set on. See :doc:`alternate_domains` for more information.
+.. note::
+    The default language of a custom domain is determined by the language of the
+    parent project that the domain was configured on. See
+    :doc:`alternate_domains` for more information.
 
 .. note:: You can include multiple translations in the same repository,
           with same ``conf.py`` and ``.rst`` files,

docs/symlinks.rst

@@ -12,15 +12,15 @@ Nginx
 
 We handle a couple of different types of requests in nginx:
 
-* Requests to a readthedocs.org subdomain
-* Requests to a CNAME
+* Requests to a ``readthedocs.io`` subdomain
+* Requests to a custom domain
 
 Subdomains
 ----------
 
-For subdomains this is a simple lookup.
-This doesn't require symlinks,
-but it shows the basic logic that we need to replicate.
+For subdomains, this is a simple lookup of the project slug, using the subdomain
+portion of the request's hostname. This doesn't require symlinks, but it shows
+the basic logic that we need to replicate.
 
 When a user navigates to ``http://pip.readthedocs.org/en/latest/``,
 we know that they want the pip documentation.
@@ -46,10 +46,10 @@ So we simply serve them the documentation:
           This will cause things to hit the Python backend,
           so that proper action can be taken.
 
-CNAMEs
-------
+Custom domains
+--------------
 
-CNAMEs add a bit of difficulty,
+Custom domains add a bit of difficulty,
 because at the nginx layer we don't know what documentation to serve.
 When someone requests ``http://docs.fabfile.org/en/latest/``,
 we can't look at the URL to know to serve the ``fabric`` docs.