New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from Sep 13, 2018
Jump to file or symbol
Failed to load files and symbols.
+40 −40
Diff settings

Always

Just for now

Copy path View file
@@ -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::
Copy path View file
@@ -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?
--------------------------------------------------
Copy path View file
@@ -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.

This comment has been minimized.

@davidfischer

davidfischer Sep 10, 2018

Contributor

customer -> custom

Copy path View file
@@ -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,
Copy path View file
@@ -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.

This comment has been minimized.

@RichardLitt

RichardLitt Sep 10, 2018

Member

I think only the company is capitalized. On the nginx website, it is consistently lower-cased.

When someone requests ``http://docs.fabfile.org/en/latest/``,
we can't look at the URL to know to serve the ``fabric`` docs.
ProTip! Use n and p to navigate between commits in a pull request.