-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should it be enclosed in double ``
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right!
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. |
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For now, this pattern is better than nothing. I do dislike combining docs in our community side, but i agree we need something for now. Noted copy changes.
docs/alternate_domains.rst
Outdated
@@ -1,12 +1,18 @@ | |||
Alternate Domains |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Alternate Domain" here, and no need for title capitalization.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Alternate domains here
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CNAME -> custom domain
docs/business/alternate_domains.rst
Outdated
CNAME SSL | ||
--------- | ||
|
||
We do support SSL for CNAMEs on our side. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We actually require it for private projects, we should note that here instead.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I believe this might change if the project is public?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
But also, if not, we should update the docs here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
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