From cd6e7730f267758825f4834be8ce9f13d9a4703f Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 1 Apr 2020 00:02:08 -0500 Subject: [PATCH 1/8] Rework custom domains docs - Merge docs for custom domains for .org and .com - Merge `Custom domain support` and `Custom Domain SSL` sections - Simplify some paragraphs --- docs/commercial/custom_domains.rst | 39 --------- docs/custom_domains.rst | 133 ++++++++++++++++------------- 2 files changed, 75 insertions(+), 97 deletions(-) delete mode 100644 docs/commercial/custom_domains.rst diff --git a/docs/commercial/custom_domains.rst b/docs/commercial/custom_domains.rst deleted file mode 100644 index 1eb46ec723d..00000000000 --- a/docs/commercial/custom_domains.rst +++ /dev/null @@ -1,39 +0,0 @@ -Custom Domains -============== - -.. note:: These directions are for projects hosted on Read the Docs for Business. - For setting up a custom domain on a project hosted on readthedocs.org, - please read our :doc:`community documentation `. - -Subdomain support ------------------ - -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, continue on to custom domain setup. - - -Serving documentation with a custom domain ------------------------------------------- - -Projects can also be hosted under a custom domain. -If you'd prefer to use your own domain name instead of our default hosting domain, -you can still host with us. - - -We require two steps from your side: - -* Add a CNAME record in your DNS that points to our servers ``.users.readthedocs.com`` -* Set your project's Privacy Level to *Public* from :guilabel:`Admin` > :guilabel:`Advance Settings`. -* Add a Domain in the :guilabel:`Admin` > :guilabel:`Domains` 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.com``. - - -Custom domain SSL ------------------ - -We require SSL for custom domains. -During the setup process, you will need to add a record to your DNS -which will allow us to issue an SSL certificate for your custom domain. diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index bd956176a22..9f04a8a79e1 100644 --- a/docs/custom_domains.rst +++ b/docs/custom_domains.rst @@ -1,85 +1,98 @@ 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 `_, - please read our :doc:`commercial documentation `. +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 +----------------- -Subdomain Support ------------------- +Every project has a subdomain that is available to serve its documentation. +If you go to ``.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 ``.readthedocs-hosted.com``. -Every project has a subdomain that is available to serve its documentation. If you go to ``.readthedocs.io``, it should show you the latest version of documentation. A good example is https://pip.readthedocs.io +.. note:: -.. 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. + 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. -Custom Domain Support ---------------------- -You can also host your documentation from your own domain by adding a domain to -your project: +Custom domain support +--------------------- -* 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 + + - 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` -Custom Domain SSL ------------------ + 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. -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. + For example, https://pip.pypa.io resolves, but is hosted on our infrastructure. + As another example, fabric's dig record looks like this: -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`). + .. prompt:: bash $, auto -If your domain has configured CAA records, please do not forget to include -Cloudflare CAA entries, see their `Certification Authority Authorization (CAA) -FAQ `_. + $ dig docs.fabfile.org + ... + ;; ANSWER SECTION: + docs.fabfile.org. 7200 IN CNAME readthedocs.io. -.. note:: + .. 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. - 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`). + 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. - If you change the CNAME record, the SSL certificate issuance can take about - one hour. + **Notes for Cloudflare users** -.. important:: + - If your domain has configured CAA records, please do not forget to include + Cloudflare CAA entries, see their `Certification Authority Authorization (CAA) + FAQ `__. - 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``. + - 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`_. - For more details, see this `previous issue`_. + .. _this previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395 - .. _previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395 + .. tab:: Read the Docs for Business + - 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 + + 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 ``.users.readthedocs.com``. + These domains will continue to resolve. Proxy SSL --------- @@ -115,7 +128,11 @@ An example nginx configuration for pip would look like: } } -rtfd.org ---------- +Other domains +------------- + +You can also use ``rtfd.io`` and ``rtfd.org`` for short URLs for projects hosted on the community version of Read the Docs. +For example: -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`. +- https://pip.rtfd.io redirects to pip's documentation page +- https://rtfd.io/projects/pip redirects to pip's dashboard page From e286b49dd067b6b062da8dd826efa08255cddd02 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 1 Apr 2020 09:27:52 -0500 Subject: [PATCH 2/8] Remove from index --- docs/commercial/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/commercial/index.rst b/docs/commercial/index.rst index 87c84258b7c..85bd5d1fdb5 100644 --- 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 From 2845430baa20ad5c19558854e17ca452993826e9 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 7 Apr 2020 10:23:51 -0500 Subject: [PATCH 3/8] Apply suggestions from code review Co-Authored-By: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/custom_domains.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index 9f04a8a79e1..1e53c735746 100644 --- a/docs/custom_domains.rst +++ b/docs/custom_domains.rst @@ -34,6 +34,8 @@ You can also host your documentation from your own domain. .. tab:: Read the Docs Community +In order to setup your custom domain, follow these steps: + - 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` @@ -83,7 +85,7 @@ You can also host your documentation from your own domain. - 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 + - 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, From 135a8bf2cb4c14f84c058a84821d22a782ef7d63 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 7 Apr 2020 10:46:05 -0500 Subject: [PATCH 4/8] Suggestions from review --- docs/custom_domains.rst | 55 ++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 31 deletions(-) diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index 1e53c735746..34cb8ba8dda 100644 --- a/docs/custom_domains.rst +++ b/docs/custom_domains.rst @@ -34,12 +34,12 @@ You can also host your documentation from your own domain. .. tab:: Read the Docs Community -In order to setup your custom domain, follow these steps: + In order to setup your custom domain, follow these steps: - - 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` + #. 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, we provide a validated SSL certificate for the domain. This service is generously provided by Cloudflare. @@ -63,29 +63,31 @@ In order to setup your custom domain, follow these steps: they do not yet allow us to acquire SSL certificates for those domains. Follow the new setup to have a SSL certificate. - **Notes for Cloudflare users** + .. warning:: Notes for Cloudflare users - - If your domain has configured CAA records, please do not forget to include - Cloudflare CAA entries, see their `Certification Authority Authorization (CAA) - FAQ `__. + - If your domain has configured CAA records, please do not forget to include + Cloudflare CAA entries, see their `Certification Authority Authorization (CAA) + FAQ `__. - - 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``. + For more details, see `this previous issue`_. - .. _this previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395 + .. _this previous issue: https://github.com/readthedocs/readthedocs.org/issues/4395 .. tab:: Read the Docs for Business - - 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. + 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, @@ -129,12 +131,3 @@ An example nginx configuration for pip would look like: proxy_read_timeout 20s; } } - -Other domains -------------- - -You can also use ``rtfd.io`` and ``rtfd.org`` for short URLs for projects hosted on the community version of Read the Docs. -For example: - -- https://pip.rtfd.io redirects to pip's documentation page -- https://rtfd.io/projects/pip redirects to pip's dashboard page From 67c8b63d11472732efb6b7c730330a75343def51 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 7 Apr 2020 10:47:21 -0500 Subject: [PATCH 5/8] Long line --- docs/custom_domains.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index 34cb8ba8dda..53bf8f7b768 100644 --- a/docs/custom_domains.rst +++ b/docs/custom_domains.rst @@ -87,7 +87,9 @@ You can also host your documentation from your own domain. #. 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. + #. 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, From 738b6b2836a7e0cadad48e7f407fdeaf7ba7a1d7 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 7 Apr 2020 13:43:08 -0500 Subject: [PATCH 6/8] Allow to link to a specific tab --- docs/_static/js/expand_tabs.js | 17 +++++++++++++++++ docs/conf.py | 5 +---- 2 files changed, 18 insertions(+), 4 deletions(-) create mode 100644 docs/_static/js/expand_tabs.js diff --git a/docs/_static/js/expand_tabs.js b/docs/_static/js/expand_tabs.js new file mode 100644 index 00000000000..ceaeaef6f55 --- /dev/null +++ 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/conf.py b/docs/conf.py index 72e2af1aff6..d488aec5c2c 100644 --- 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 = { From 79b937e8495a8be64fde9a24eec4380216b680a6 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 13 Apr 2020 09:54:12 -0500 Subject: [PATCH 7/8] Add note about proxy ssl --- docs/custom_domains.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index 53bf8f7b768..5184217582e 100644 --- a/docs/custom_domains.rst +++ b/docs/custom_domains.rst @@ -103,6 +103,10 @@ You can also host your documentation from your own domain. Proxy SSL --------- +.. note:: + + This is only available for the community version + 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. From 8ebded69160f495c56e2966da90bad3be2dc9f5f Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 13 Apr 2020 10:11:58 -0500 Subject: [PATCH 8/8] Deprecate proxy ssl --- docs/custom_domains.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index 5184217582e..eb30e40b53a 100644 --- a/docs/custom_domains.rst +++ b/docs/custom_domains.rst @@ -103,9 +103,10 @@ You can also host your documentation from your own domain. Proxy SSL --------- -.. note:: +.. warning:: - This is only available for the community version + 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,