882927 - Figure out MDN URLs & linking for docs published on ReadTheDocs.org

Status: RESOLVED INVALID

(developer.mozilla.org Graveyard :: General, defect)

Description

[Les Orchard [:lorchard]]

Assuming we defer bug 882919 for later, we can publish docs to ReadTheDocs.org right now with an MDN-flavored theme (bug 873256). That leaves the problem of URLs and linking.

By default, ReadTheDocs.org offer URLs like this:

    https://firefox-marketplace-api.readthedocs.org/en/latest/

However, for many reasons, we might want these docs to appear from Mozilla-controlled domains. For this, ReadTheDocs.org offers CNAME support:

    http://read-the-docs.readthedocs.org/en/latest/alternate_domains.html

So, for example, we could have docs at URLs like this:

    https://firefox-marketplace-api.developer.mozilla.org/

This would require some coordination with IT to set up the CNAMEs in our DNS, and there are probably some other issues. I'm filing this bug to get the ball rolling on collecting these issues and sussing out the infrastructure implications.

Comment 1

[Luke Crouch [:groovecoder]]

After thinking about this and bug 883221, I'd rather try to serve ReadTheDocs content (zones) from URI paths on MDN instead of sub-domains - if we can do it?

https://developer.mozilla.org/en-US/docs/FirefoxMarketplaceAPI/overview.html 
vs.
https://firefox-marketplace-api.developer.mozilla.org/en/latest/topics/overview.html

Is that any better? Could we do it by proxying requests?

Comment 2

[Les Orchard [:lorchard]]

(In reply to Luke Crouch [:groovecoder] from comment #1)

> Is that any better? Could we do it by proxying requests?

The URLs are way better, definitely. I thought that proxying would be problematic, but I just tried adding this to my .htaccess

    RewriteRule ^en-US/docs/FirefoxMarketplaceAPI/(.*)$ https://firefox-marketplace-api.readthedocs.org/en/latest/$1 [L,P]

And, surprisingly to me, that seems to work fine. Try adding that to your local configs/htaccess-without-mindtouch just before the line with /mwsgi. Click around, see if anything breaks. I haven't seen a problem with half-a-dozen clicks in.

It can't be that easy, can it? Because if it is, that solves a whole pile of issues.

Comment 3

[Luke Crouch [:groovecoder]]

Lulz. Wow that works fine for me too. So I went ahead and added:

RewriteRule ^en-US/docs/DjangoBrowserID/(.*)$ http://django-browserid.readthedocs.org/en/latest/$1 [L,P]

Guess what ... :)

Comment 4

[Les Orchard [:lorchard]]

One downside to proxying is I think it makes us more vulnerable security-wise until we have on-premises publishing (bug 882920, bug 882919).

I think the subdomains at least would have put some separation between 3rd party published docs and MDN proper. Now, those docs will have access to MDN cookies.

Practically speaking, I think it's okay, because you'd have to compromise github or Read the Docs to compromise MDN. Still, it's a concern to consider.

Comment 5

[Les Orchard [:lorchard]]

Some more thoughts:

* We should reach out to Read the Docs & GitHub Pages folks and make sure this proxying isn't seen as an abuse of the respective services

* Anything under the /{locale}/docs/{...} URLspace will conflict with the wiki. We need to:
   
    1) restrict the space carved out, possibly with a prefix (ie. /en-US/docs/Projects/DjangoBrowserID/)
   
    2) register these "mount points" in URLspace with the wiki, so that attempts to create / move / edit pages in those spaces are prevented