Skip to content
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

Merged
merged 3 commits into from Nov 1, 2018

Conversation

@humitos
Copy link
Member

@humitos humitos commented Jun 19, 2018

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: readthedocs/readthedocs-corporate#247

@humitos humitos requested a review from Jun 19, 2018
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
Copy link
Member

@stsewd stsewd Jun 19, 2018

Should it be enclosed in double ``?

Copy link
Member Author

@humitos humitos Jun 19, 2018

Right!

@humitos humitos force-pushed the humitos/docs/alternate-domains-business branch from 682ce92 to 968a552 Jun 19, 2018
@agjohnson
Copy link
Contributor

@agjohnson agjohnson commented Jun 19, 2018

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.

@agjohnson agjohnson added this to the Documentation milestone Jun 19, 2018
@humitos humitos force-pushed the humitos/docs/alternate-domains-business branch from 968a552 to 977473a Jun 25, 2018
@humitos
Copy link
Member Author

@humitos humitos commented Jun 25, 2018

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 (readthedocs/readthedocs-corporate#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.

Copy link
Contributor

@agjohnson agjohnson left a comment

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.

@@ -1,12 +1,18 @@
Alternate Domains
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

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".

Copy link
Member Author

@humitos humitos Oct 3, 2018

This will require a file rename and a redirection added.

@@ -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`_,
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

"Alternate Domain" here, and no need for title capitalization.

Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

Also, on readthedocs.com, this should be "commercial hosting"

@@ -1,12 +1,18 @@
Alternate Domains
=================

.. note:: This documentation belongs to our community site.
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

The note here should probably be something more clear. "These setup directions are for our community site" or something similar

@@ -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>`.
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

We should also rename the "business/" docs. We don't refer to our commercial hosting as "business" anywhere else.

@@ -0,0 +1,32 @@
Alternate Domains
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

Alternate domains here

CNAME Support
-------------

If you have your own domain, you can still host with us.
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

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

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``
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

There are more steps here though. We need to discuss set up if your project is private and setup if your project is public.

Copy link
Member Author

@humitos humitos Oct 3, 2018

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.

Copy link
Member Author

@humitos humitos Oct 3, 2018

What else ir required if your project is public?

* 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.
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

title capitalization on Domain can be removed.

.. 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
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

CNAME -> custom domain

CNAME SSL
---------

We do support SSL for CNAMEs on our side.
Copy link
Contributor

@agjohnson agjohnson Aug 3, 2018

We actually require it for private projects, we should note that here instead.

@humitos humitos force-pushed the humitos/docs/alternate-domains-business branch 2 times, most recently from b0dbe59 to 1090e7f Oct 3, 2018
@humitos
Copy link
Member Author

@humitos humitos commented Oct 3, 2018

@agjohnson this PR should be ready for re-review.

@humitos humitos requested a review from agjohnson Oct 3, 2018
@humitos
Copy link
Member Author

@humitos humitos commented Oct 17, 2018

Once this gets merged, we need to write a Redirect since I renamed business/ to commercial/ directory.

@ericholscher
Copy link
Member

@ericholscher ericholscher commented Oct 17, 2018

Once this gets merged, we need to write a Redirect since I renamed business/ to commercial/ directory.

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.
Copy link
Member Author

@humitos humitos Oct 25, 2018

@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.

Copy link
Contributor

@agjohnson agjohnson Oct 26, 2018

I believe this might change if the project is public?

Copy link
Contributor

@agjohnson agjohnson Oct 26, 2018

But also, if not, we should update the docs here.

Copy link
Member Author

@humitos humitos Nov 1, 2018

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.

@ericholscher
Copy link
Member

@ericholscher ericholscher commented Oct 31, 2018

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 :)

@humitos
Copy link
Member Author

@humitos humitos commented Nov 1, 2018

Should be able to create it now, and it won't do anything until it 404's.

I created the redirects and I will merge this PR once the CI passes.

humitos added 3 commits Nov 1, 2018
* use commercial instead of business
* Custom Domain instead CNAM
* paraphrase some sentences
* rename alternate_domain.rst to custom_domain.rst
@humitos humitos force-pushed the humitos/docs/alternate-domains-business branch from 1228de4 to 57177e7 Nov 1, 2018
@codecov
Copy link

@codecov codecov bot commented Nov 1, 2018

Codecov Report

Merging #4271 into master will not change coverage.
The diff coverage is n/a.

@@           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

@humitos humitos merged commit acc8ef2 into master Nov 1, 2018
3 checks passed
@humitos humitos deleted the humitos/docs/alternate-domains-business branch Nov 1, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants