From 66edd5a24faa674d58166dae6558a2b0fee63e9f Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Mon, 10 Sep 2018 11:59:14 -0600 Subject: [PATCH 1/2] Change mentions of "CNAME" -> custom domain Also some related cleanup of copy around the CNAME -> custom domain changes. --- docs/alternate_domains.rst | 39 ++++++++++++++++++-------------------- docs/faq.rst | 14 +++++++------- docs/features.rst | 2 +- docs/localization.rst | 5 ++++- docs/symlinks.rst | 20 +++++++++---------- 5 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/alternate_domains.rst b/docs/alternate_domains.rst index 8a9ec67229c..4bd0cc2e079 100644 --- a/docs/alternate_domains.rst +++ b/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 `_ 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 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:: diff --git a/docs/faq.rst b/docs/faq.rst index f1bf0c7af2c..d7f5690d295 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -112,12 +112,12 @@ 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, @@ -125,11 +125,11 @@ 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? -------------------------------------------------- diff --git a/docs/features.rst b/docs/features.rst index f0ceb1336be..27679344627 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -65,4 +65,4 @@ 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 customer domains, subdomains, and a shorturl for your project as well. This is outlined in the :doc:`alternate_domains` section. diff --git a/docs/localization.rst b/docs/localization.rst index 9d25e60d5d2..695c2a879fe 100644 --- a/docs/localization.rst +++ b/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, diff --git a/docs/symlinks.rst b/docs/symlinks.rst index 91308541f5e..36b3804d1e5 100644 --- a/docs/symlinks.rst +++ b/docs/symlinks.rst @@ -1,7 +1,7 @@ How we use symlinks =================== -Read the Docs stays highly available by serving all documentation pages out of nginx. +Read the Docs stays highly available by serving all documentation pages out of Nginx. This means that they never hit our Python layer, meaning that they never hit our database. This reduces the total number of servers to serve a request to 1, @@ -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,11 +46,11 @@ 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, -because at the nginx layer we don't know what documentation to serve. +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. From 60668ef7a87db47cdb5ea230a35c1119366cb4ac Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Mon, 10 Sep 2018 20:37:21 -0600 Subject: [PATCH 2/2] Fix typo and do Nginx -> nginx --- docs/features.rst | 3 ++- docs/symlinks.rst | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/features.rst b/docs/features.rst index 27679344627..6cffa56c540 100644 --- a/docs/features.rst +++ b/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 customer domains, 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. diff --git a/docs/symlinks.rst b/docs/symlinks.rst index 36b3804d1e5..972ed694e4c 100644 --- a/docs/symlinks.rst +++ b/docs/symlinks.rst @@ -1,7 +1,7 @@ How we use symlinks =================== -Read the Docs stays highly available by serving all documentation pages out of Nginx. +Read the Docs stays highly available by serving all documentation pages out of nginx. This means that they never hit our Python layer, meaning that they never hit our database. This reduces the total number of servers to serve a request to 1, @@ -50,7 +50,7 @@ Custom domains -------------- Custom domains add a bit of difficulty, -because at the Nginx layer we don't know what documentation to serve. +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.