Document alternate domains for business site #4271
Conversation
docs/alternate_domains.rst
Outdated
| 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 documentation. A good example is http://pip.readthedocs.io | ||
| 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 http://pip.readthedocs.io |
There was a problem hiding this comment.
Should it be enclosed in double ``?
humitos
force-pushed
the
humitos/docs/alternate-domains-business
branch
from
682ce92
to
968a552
Compare
|
I think we need a separate set of docs, which is the project i was working on. I'm not convinced we should be combining our docs here, or documenting .com features. I'll come back to this later for some review of the copy. |
humitos
force-pushed
the
humitos/docs/alternate-domains-business
branch
from
968a552
to
977473a
Compare
|
I agree with @agjohnson, but in the other hand, I think this is a quick solution to avoid confusions to our customers on .com and make us to spend more support time on this. These docs, together with the PR that rework the Admin page (https://github.com/rtfd/readthedocs-corporate/pull/359) is the first step I'd say. Splitting the docs will take some time I believe since it's not yet defined how/what we want to do it and I think we need to move faster here. Reverting these changes once we have the docs split is trivial, I think. |
docs/alternate_domains.rst
Outdated
| @@ -1,12 +1,18 @@ | |||
| Alternate Domains | |||
There was a problem hiding this comment.
We should rename this doc entirely. Nomenclature for this feature should be "custom domains". We use "CNAME" a lot, which is not clear, and I think this is the only place we refer to this as "alternate domains".
There was a problem hiding this comment.
This will require a file rename and a redirection added.
docs/alternate_domains.rst
Outdated
| @@ -1,12 +1,18 @@ | |||
| Alternate Domains | |||
| ================= | |||
|
|
|||
| .. note:: This documentation belongs to our community site. | |||
| If you want to setup an Alternate Domain under `readthedocs.com`_, | |||
There was a problem hiding this comment.
"Alternate Domain" here, and no need for title capitalization.
There was a problem hiding this comment.
Also, on readthedocs.com, this should be "commercial hosting"
docs/alternate_domains.rst
Outdated
| @@ -1,12 +1,18 @@ | |||
| Alternate Domains | |||
| ================= | |||
|
|
|||
| .. note:: This documentation belongs to our community site. | |||
There was a problem hiding this comment.
The note here should probably be something more clear. "These setup directions are for our community site" or something similar
docs/alternate_domains.rst
Outdated
| @@ -1,12 +1,18 @@ | |||
| Alternate Domains | |||
| ================= | |||
|
|
|||
| .. note:: This documentation belongs to our community site. | |||
| If you want to setup an Alternate Domain under `readthedocs.com`_, | |||
| please read our :ref:`business documentation <business/alternate_domains:Alternate Domains>`. | |||
There was a problem hiding this comment.
We should also rename the "business/" docs. We don't refer to our commercial hosting as "business" anywhere else.
docs/business/alternate_domains.rst
Outdated
| @@ -0,0 +1,32 @@ | |||
| Alternate Domains | |||
docs/business/alternate_domains.rst
Outdated
| CNAME Support | ||
| ------------- | ||
|
|
||
| If you have your own domain, you can still host with us. |
There was a problem hiding this comment.
To turn a negative sentiment statement into a positive one, this could be something similar to:
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
docs/business/alternate_domains.rst
Outdated
| If you have your own domain, you can still host with us. | ||
| This requires two steps: | ||
|
|
||
| * Add a CNAME record in your DNS that points to our servers ``<organization-slug>.users.readthedocs.com`` |
There was a problem hiding this comment.
There are more steps here though. We need to discuss set up if your project is private and setup if your project is public.
There was a problem hiding this comment.
I suppose these two steps are the same for private/public, right?
I left them and I mentioned that after doing these, it's needed to contact the support team.
There was a problem hiding this comment.
What else ir required if your project is public?
docs/business/alternate_domains.rst
Outdated
| * Add a CNAME record in your DNS that points to our servers ``<organization-slug>.users.readthedocs.com`` | ||
| * Add a Domain in the **Project Admin > Domains** page for your project. | ||
|
|
||
| .. note:: The Domain that should be used is the actual subdomain that you want your docs served on. |
There was a problem hiding this comment.
title capitalization on Domain can be removed.
docs/business/alternate_domains.rst
Outdated
| .. 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``. | ||
|
|
||
| CNAME SSL |
docs/business/alternate_domains.rst
Outdated
| CNAME SSL | ||
| --------- | ||
|
|
||
| We do support SSL for CNAMEs on our side. |
There was a problem hiding this comment.
We actually require it for private projects, we should note that here instead.
humitos
force-pushed
the
humitos/docs/alternate-domains-business
branch
2 times, most recently
from
b0dbe59
to
1090e7f
Compare
|
@agjohnson this PR should be ready for re-review. |
|
Once this gets merged, we need to write a Redirect since I renamed |
Should be able to create it now, and it won't do anything until it 404's. Also this is an obvious endorsement for redirects in our YAML file, if we can figure out a good way to handle it. |
| We require two steps from your side: | ||
|
|
||
| * Add a CNAME record in your DNS that points to our servers ``<organization-slug>.users.readthedocs.com`` | ||
| * Add a Domain in the **Project Admin > Domains** page for your project. |
There was a problem hiding this comment.
@agjohnson It seems this is not possible to do this by them at this point, since only the "Contact us" button appear in that page.
There was a problem hiding this comment.
I believe this might change if the project is public?
There was a problem hiding this comment.
But also, if not, we should update the docs here.
There was a problem hiding this comment.
You are right. If you change your project to public, it's possible to add the domain. I'm adding another step for this before this bullet and merging after that.
|
This looks like a solid improvement to me. I'm +1 on merging it and improving later if we need to, but it's definitely better than the current docs :) |
I created the redirects and I will merge this PR once the CI passes. |
* use commercial instead of business * Custom Domain instead CNAM * paraphrase some sentences * rename alternate_domain.rst to custom_domain.rst
humitos
force-pushed
the
humitos/docs/alternate-domains-business
branch
from
1228de4
to
57177e7
Compare
Codecov Report
@@ Coverage Diff @@
## master #4271 +/- ##
=======================================
Coverage 76.39% 76.39%
=======================================
Files 158 158
Lines 9980 9980
Branches 1261 1261
=======================================
Hits 7624 7624
Misses 2016 2016
Partials 340 340 |
We are missing a good documentation for setup custom domains in our corporate site.
This PR adds a page that explains it for .com customers.
There are more work to do in the Domains page under Admin for the corporate site, but that will be done in a different PR.
Ref: https://github.com/rtfd/readthedocs-corporate/issues/247