readthedocs · stsewd · Apr 13, 2020 · Apr 1, 2020 · Apr 1, 2020 · Apr 7, 2020
diff --git a/docs/_static/js/expand_tabs.js b/docs/_static/js/expand_tabs.js
@@ -0,0 +1,17 @@
+/*
+ * Expands a specific tab of sphinx-tabs.
+ * Usage:
+ * - docs.readthedocs.io/?tab=Name
+ * - docs.readthedocs.io/?tab=Name#section
+ * Where 'Name' is the title of the tab (case sensitive).
+*/
+$( document ).ready(function() {
+  const urlParams = new URLSearchParams(window.location.search);
+  const tabName = urlParams.get('tab');
+  if (tabName !== null) {
+    const tab = $('a.item > div:contains("' + tabName + '")');
+    if (tab.length > 0) {
+      tab.click();
+    }
+  }
+});
diff --git a/docs/commercial/custom_domains.rst b/docs/commercial/custom_domains.rst
diff --git a/docs/commercial/index.rst b/docs/commercial/index.rst
@@ -32,7 +32,6 @@ Advertising-free
 .. toctree:: 
    :caption: Additional commercial features
 
-   custom_domains
    organizations
    sharing
    analytics
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,7 +1,3 @@
-# -*- coding: utf-8 -*-
-
-from __future__ import division, print_function, unicode_literals
-
 import os
 import sys
 from configparser import RawConfigParser
@@ -81,6 +77,7 @@ def get_version():
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
+html_js_files = ['js/expand_tabs.js']
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_logo = 'img/logo.svg'
 html_theme_options = {

diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst
@@ -1,89 +1,113 @@
 Custom Domains
 ==============
 
-.. note:: These directions are for projects hosted on our community site.
-          If you want to setup a custom domain on `Read the Docs for Business <https://readthedocs.com/>`_,
-          please read our :doc:`commercial documentation <commercial/custom_domains>`.
+Once a project is imported into Read the Docs,
+by default it's hosted under a subdomain on one of our domains.
+If you need a custom domain, see :ref:`custom_domains:custom domain support`.
 
-Read the Docs supports a number of custom domains for your convenience. Shorter URLs make everyone happy, and we like making people happy!
+Subdomain support
+-----------------
+
+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 your documentation.
+A good example is https://pip.readthedocs.io
+For :doc:`/commercial/index` the subdomain looks like ``<slug>.readthedocs-hosted.com``.
 
-Subdomain Support
-------------------
+.. note::
 
-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
+   If you have an old project that has an underscore (_) in the name,
+   it will use a subdomain with a hyphen (-).
+   `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.
 
-.. note:: If you have an old project that has an underscore (_) in the name, it will use a subdomain with a hyphen (-).
-          `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.
 
-Custom Domain Support
+Custom domain support
 ---------------------
 
-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 points the domain to: ``readthedocs.io``
-* Add a project domain in the :guilabel:`Domains` project admin page for your project.
+You can also host your documentation from your own domain.
 
 .. 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.
+   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.
 
-As another example, fabric's dig record looks like this::
+.. tabs::
 
-    -> dig docs.fabfile.org
-    ...
-    ;; ANSWER SECTION:
-    docs.fabfile.org.   7200    IN  CNAME   readthedocs.io.
+   .. tab:: Read the Docs Community
+
+      In order to setup your custom domain, follow these steps:
 
-Custom Domain SSL
------------------
+      #. Add a CNAME record in your DNS that points the domain to ``readthedocs.io``
+      #. Go the :guilabel:`Admin` tab of your project
+      #. Click on :guilabel:`Domains`
+      #. Enter your domain and click on :guilabel:`Add`
 
-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.
+      By default, we provide a validated SSL certificate for the domain.
+      This service is generously provided by Cloudflare.
+      The SSL certificate issuance can take about one hour,
+      you can see the status of the certificate on the domain page in your project.
 
-After configuring your custom domain on Read the Docs,
-you can see the status of the certificate on the domain page in your project
-admin dashboard (:guilabel:`Domains` > :guilabel:`Edit Domain`).
+      For example, https://pip.pypa.io resolves, but is hosted on our infrastructure.
+      As another example, fabric's dig record looks like this:
 
-If your domain has configured CAA records, please do not forget to include
-Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
-FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`_.
+      .. prompt:: bash $, auto
 
-.. note::
+         $ dig docs.fabfile.org
+         ...
+         ;; ANSWER SECTION:
+         docs.fabfile.org.   7200    IN  CNAME   readthedocs.io.
+
+      .. note::
+
+         Some older setups configured a CNAME record pointing to ``readthedocs.org`` or another variation.
+         While these continue to resolve,
+         they do not yet allow us to acquire SSL certificates for those domains.
+         Follow the new setup to have a SSL certificate.
 
-    Some older setups configured a CNAME record pointing to ``readthedocs.org``
-    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``, with no subdomain, and re-request a certificate
-    by saving the domain in the project admin (:guilabel:`Domains` >
-    :guilabel:`Edit Domain`).
+      .. warning:: Notes for Cloudflare users
 
-    If you change the CNAME record, the SSL certificate issuance can take about
-    one hour.
+         - If your domain has configured CAA records, please do not forget to include
+           Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
+           FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`__.
 
-.. important::
+         - Due to a limitation,
+           a domain cannot be proxied on Cloudflare to another Cloudflare account that also proxies.
+           This results in a "CNAME Cross-User Banned" error.
+           In order to do SSL termination, we must proxy this connection.
+           If you don't want us to do SSL termination for your domain —
+           **which means you are responsible for the SSL certificate** —
+           then set your CNAME to ``cloudflare-to-cloudflare.readthedocs.io`` instead of ``readthedocs.io``.
+           For more details, see `this previous issue`_.
 
-    Due to a limitation, a domain cannot be proxied on Cloudflare
-    to another Cloudflare account that also proxies.
-    This results in a "CNAME Cross-User Banned" error.
-    In order to do SSL termination, we must proxy this connection.
-    If you don't want us to do SSL termination for your domain --
-    **which means you are responsible for the SSL certificate** --
-    then set your CNAME to ``cloudflare-to-cloudflare.readthedocs.io``
-    instead of ``readthedocs.io``.
+           .. _this previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395
 
-    For more details, see this `previous issue`_.
+   .. tab:: Read the Docs for Business
 
-    .. _previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395
+      In order to setup your custom domain, follow these steps:
 
+      #. Go the :guilabel:`Admin` tab of your project
+      #. Click on :guilabel:`Domains`
+      #. Enter your domain and click on :guilabel:`Add`
+      #. Follow the steps shown on the domain page.
+         This will require adding 2 DNS records, one pointing your custom domain to our servers,
+         and another allowing us to provision an SSL certificate. 
+
+      By default, we provide a validated SSL certificate for the domain.
+      The SSL certificate issuance can take a few days,
+      you can see the status of the certificate on the domain page in your project.
+
+      .. note::
+
+         Some older setups configured a CNAME record pointing to ``<organization-slug>.users.readthedocs.com``.
+         These domains will continue to resolve.
 
 Proxy SSL
 ---------
 
+.. warning::
+
+   This option is deprecated,
+   we already issue SSL certificates for all domains.
+
 If you would prefer to do your own SSL termination
 on a server you own and control,
 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:
             proxy_read_timeout 20s;
         }
     }
-
-rtfd.org
----------
-
-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`.