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/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/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 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 = { diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index bd956176a22..eb30e40b53a 100644 --- 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 `_, - 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 +----------------- + +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``. -Subdomain Support ------------------- +.. note:: -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 + 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. -.. 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. -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 `_. + .. 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 `__. -.. 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 ``.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`.