Skip to content

Commit 95a2eaf

Browse files
stsewdstsewd
authored
Merge pull request #6844 from readthedocs/rework-custom-domains-docs
Rework custom domains docs
2 parents c8aeb68 + 8ebded6 commit 95a2eaf

File tree

5 files changed

+97
-104
lines changed

5 files changed

+97
-104
lines changed

‎docs/_static/js/expand_tabs.js

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/*
2+
* Expands a specific tab of sphinx-tabs.
3+
* Usage:
4+
* - docs.readthedocs.io/?tab=Name
5+
* - docs.readthedocs.io/?tab=Name#section
6+
* Where 'Name' is the title of the tab (case sensitive).
7+
*/
8+
$( document ).ready(function() {
9+
const urlParams = new URLSearchParams(window.location.search);
10+
const tabName = urlParams.get('tab');
11+
if (tabName !== null) {
12+
const tab = $('a.item > div:contains("' + tabName + '")');
13+
if (tab.length > 0) {
14+
tab.click();
15+
}
16+
}
17+
});

‎docs/commercial/custom_domains.rst

-39
This file was deleted.

‎docs/commercial/index.rst

-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,6 @@ Advertising-free
3232
.. toctree::
3333
:caption: Additional commercial features
3434

35-
custom_domains
3635
organizations
3736
sharing
3837
analytics

‎docs/conf.py

+1-4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
# -*- coding: utf-8 -*-
2-
3-
from __future__ import division, print_function, unicode_literals
4-
51
import os
62
import sys
73
from configparser import RawConfigParser
@@ -81,6 +77,7 @@ def get_version():
8177

8278
html_theme = 'sphinx_rtd_theme'
8379
html_static_path = ['_static']
80+
html_js_files = ['js/expand_tabs.js']
8481
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
8582
html_logo = 'img/logo.svg'
8683
html_theme_options = {

‎docs/custom_domains.rst

+79-60
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,113 @@
11
Custom Domains
22
==============
33

4-
.. note:: These directions are for projects hosted on our community site.
5-
If you want to setup a custom domain on `Read the Docs for Business <https://readthedocs.com/>`_,
6-
please read our :doc:`commercial documentation <commercial/custom_domains>`.
4+
Once a project is imported into Read the Docs,
5+
by default it's hosted under a subdomain on one of our domains.
6+
If you need a custom domain, see :ref:`custom_domains:custom domain support`.
77

8-
Read the Docs supports a number of custom domains for your convenience. Shorter URLs make everyone happy, and we like making people happy!
8+
Subdomain support
9+
-----------------
10+
11+
Every project has a subdomain that is available to serve its documentation.
12+
If you go to ``<slug>.readthedocs.io``, it should show you the latest version of your documentation.
13+
A good example is https://pip.readthedocs.io
14+
For :doc:`/commercial/index` the subdomain looks like ``<slug>.readthedocs-hosted.com``.
915

10-
Subdomain Support
11-
------------------
16+
.. note::
1217

13-
Every project has a subdomain that is available to serve its documentation. If you go to ``<slug>.readthedocs.io``, it should show you the latest version of documentation. A good example is https://pip.readthedocs.io
18+
If you have an old project that has an underscore (_) in the name,
19+
it will use a subdomain with a hyphen (-).
20+
`RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.
1421

15-
.. note:: If you have an old project that has an underscore (_) in the name, it will use a subdomain with a hyphen (-).
16-
`RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.
1722

18-
Custom Domain Support
23+
Custom domain support
1924
---------------------
2025

21-
You can also host your documentation from your own domain by adding a domain to
22-
your project:
23-
24-
* Add a CNAME record in your DNS that points the domain to: ``readthedocs.io``
25-
* Add a project domain in the :guilabel:`Domains` project admin page for your project.
26+
You can also host your documentation from your own domain.
2627

2728
.. note::
28-
We don't currently support pointing subdomains or naked domains to a project
29-
using ``A`` records. It's best to point a subdomain, ``docs.example.com``
30-
for example, using a CNAME record.
3129

32-
Using pip as an example, https://pip.pypa.io resolves, but is hosted on our infrastructure.
30+
We don't currently support pointing subdomains or naked domains to a project using ``A`` records.
31+
It's best to point a subdomain, ``docs.example.com`` for example, using a CNAME record.
3332

34-
As another example, fabric's dig record looks like this::
33+
.. tabs::
3534

36-
-> dig docs.fabfile.org
37-
...
38-
;; ANSWER SECTION:
39-
docs.fabfile.org. 7200 IN CNAME readthedocs.io.
35+
.. tab:: Read the Docs Community
36+
37+
In order to setup your custom domain, follow these steps:
4038

41-
Custom Domain SSL
42-
-----------------
39+
#. Add a CNAME record in your DNS that points the domain to ``readthedocs.io``
40+
#. Go the :guilabel:`Admin` tab of your project
41+
#. Click on :guilabel:`Domains`
42+
#. Enter your domain and click on :guilabel:`Add`
4343

44-
By default, when you setup a custom domain to host documentation at Read the Docs,
45-
we will attempt to provision a domain validated SSL certificate for the domain.
46-
This service is generously provided by Cloudflare.
44+
By default, we provide a validated SSL certificate for the domain.
45+
This service is generously provided by Cloudflare.
46+
The SSL certificate issuance can take about one hour,
47+
you can see the status of the certificate on the domain page in your project.
4748

48-
After configuring your custom domain on Read the Docs,
49-
you can see the status of the certificate on the domain page in your project
50-
admin dashboard (:guilabel:`Domains` > :guilabel:`Edit Domain`).
49+
For example, https://pip.pypa.io resolves, but is hosted on our infrastructure.
50+
As another example, fabric's dig record looks like this:
5151

52-
If your domain has configured CAA records, please do not forget to include
53-
Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
54-
FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`_.
52+
.. prompt:: bash $, auto
5553

56-
.. note::
54+
$ dig docs.fabfile.org
55+
...
56+
;; ANSWER SECTION:
57+
docs.fabfile.org. 7200 IN CNAME readthedocs.io.
58+
59+
.. note::
60+
61+
Some older setups configured a CNAME record pointing to ``readthedocs.org`` or another variation.
62+
While these continue to resolve,
63+
they do not yet allow us to acquire SSL certificates for those domains.
64+
Follow the new setup to have a SSL certificate.
5765

58-
Some older setups configured a CNAME record pointing to ``readthedocs.org``
59-
or another variation. While these continue to resolve,
60-
they do not yet allow us to acquire SSL certificates for those domains.
61-
Point the CNAME to ``readthedocs.io``, with no subdomain, and re-request a certificate
62-
by saving the domain in the project admin (:guilabel:`Domains` >
63-
:guilabel:`Edit Domain`).
66+
.. warning:: Notes for Cloudflare users
6467

65-
If you change the CNAME record, the SSL certificate issuance can take about
66-
one hour.
68+
- If your domain has configured CAA records, please do not forget to include
69+
Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
70+
FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`__.
6771

68-
.. important::
72+
- Due to a limitation,
73+
a domain cannot be proxied on Cloudflare to another Cloudflare account that also proxies.
74+
This results in a "CNAME Cross-User Banned" error.
75+
In order to do SSL termination, we must proxy this connection.
76+
If you don't want us to do SSL termination for your domain —
77+
**which means you are responsible for the SSL certificate** —
78+
then set your CNAME to ``cloudflare-to-cloudflare.readthedocs.io`` instead of ``readthedocs.io``.
79+
For more details, see `this previous issue`_.
6980

70-
Due to a limitation, a domain cannot be proxied on Cloudflare
71-
to another Cloudflare account that also proxies.
72-
This results in a "CNAME Cross-User Banned" error.
73-
In order to do SSL termination, we must proxy this connection.
74-
If you don't want us to do SSL termination for your domain --
75-
**which means you are responsible for the SSL certificate** --
76-
then set your CNAME to ``cloudflare-to-cloudflare.readthedocs.io``
77-
instead of ``readthedocs.io``.
81+
.. _this previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395
7882

79-
For more details, see this `previous issue`_.
83+
.. tab:: Read the Docs for Business
8084

81-
.. _previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395
85+
In order to setup your custom domain, follow these steps:
8286

87+
#. Go the :guilabel:`Admin` tab of your project
88+
#. Click on :guilabel:`Domains`
89+
#. Enter your domain and click on :guilabel:`Add`
90+
#. Follow the steps shown on the domain page.
91+
This will require adding 2 DNS records, one pointing your custom domain to our servers,
92+
and another allowing us to provision an SSL certificate.
93+
94+
By default, we provide a validated SSL certificate for the domain.
95+
The SSL certificate issuance can take a few days,
96+
you can see the status of the certificate on the domain page in your project.
97+
98+
.. note::
99+
100+
Some older setups configured a CNAME record pointing to ``<organization-slug>.users.readthedocs.com``.
101+
These domains will continue to resolve.
83102

84103
Proxy SSL
85104
---------
86105

106+
.. warning::
107+
108+
This option is deprecated,
109+
we already issue SSL certificates for all domains.
110+
87111
If you would prefer to do your own SSL termination
88112
on a server you own and control,
89113
you can do that although the setup is a bit more complex.
@@ -114,8 +138,3 @@ An example nginx configuration for pip would look like:
114138
proxy_read_timeout 20s;
115139
}
116140
}
117-
118-
rtfd.org
119-
---------
120-
121-
You can also use `rtfd.io` and `rtfd.org` for short URLs for Read the Docs. For example, https://pip.rtfd.io redirects to its documentation page. Any use of `rtfd.io` or `rtfd.org` will simply be redirected to `readthedocs.io`.

0 commit comments

Comments
 (0)