Skip to content

Refactor URL Routing for Docs - #544

Merged
ericholscher merged 16 commits into
readthedocs:masterfrom
toffer:refactor-docs-url-routing
Nov 26, 2013
Merged

ericholscher merged 16 commits into
readthedocs:masterfrom
toffer:refactor-docs-url-routing

Conversation

@toffer

@toffer toffer commented Nov 17, 2013

Copy link
Copy Markdown
Member

I'm gearing up to tackle Issue #293 (adding the ability to serve pages at the base domain, rather than redirecting to /<lang_slug>/<version_slug>/), but before I start on that, I decided to refactor how URL routing is handled for serving docs. My goal was to make the redirect logic easier to follow, and to consolidate the rewriting logic in one place.

What URLs Should Be Redirected

The main challenge of URL routing in Readthedocs is handling redirects correctly. Both in the interest of redirecting older URLs that are now obsolete, and in the interest of handling "logical-looking" URLs (leaving out the lang_slug or version_slug shouldn't result in a 404), the following redirects should be handled:

/docs/pip/          -> /docs/pip/en/latest/
/docs/pip/en/       -> /docs/pip/en/latest/
/docs/pip/latest/   -> /docs/pip/en/latest/

In addition, URLs with the 'page directory' should be redirected as well:

/docs/pip/page/installing.html  -> /docs/pip/en/latest/installing.html

The examples above are given for RTD URLs (for example, http://readthedocs.org/docs/pip/), but the same redirects should also work for subdomain URLs (http://pip.readthedocs.org/).

How It Works Now

Previously, the redirect logic was handled in several places in the codebase.

In core.views, serve_docs() handled RTD URLs, while subdomain_handler() handled subdomain URLs. Redirects were handled by a series of if/else statements to check for missing URL parameters, add the appropriate ones, and redirect.

In addition, URL parameters were modified in the URLconfs (urls.py and subdomain_urls.py).

What Has Been Refactored

  1. Now, serve_docs() is strictly concerned with serving docs. No redirects are done within serve_docs(). It handles both RTD and subdomain URLs.
  2. Since serve_docs() handles all the serving, subdomain_handler() has been removed.
  3. I created several redirect_* views to handle redirects.
  4. URLs that need to be redirected are dispatched to the appropriate redirect_* view. (Previously, they were dispatched to serve_docs() or subdomain_handler().)
  5. No URL parameters are modified in URLconfs.

Questions

Does this approach make sense? Does this seem like a helpful approach to making the redirect logic clearer?

I've added additional tests to test_redirects.py (everything passes!), but I'm concerned about making a big change to such a core part of the site. Are there some additional things I should test?

For example, the current subdomain_handler() has a section that handles aliases. From the RTD Hack Day, I got the impression that you don't use aliases for anything any more, so I don't do anything with aliases. If I got that wrong, let me know what the best way to test it is.

In addition, I don't have any testing around projects and sub-projects. Suggestions for how to test that would be helpful.

Lastly, I'm looking for any suggestions/comments/feedback. Please let me know what can be improved...or, if you think I'm on the wrong track entirely!

Previously, behavior for the following URL patterns was
inconsistent for subdomain URLS (pip.readthedocs.org/) and
RTD domain URLs (readthedocs.org/docs/pip/).

Below, I list the URL pattern, and the response status codes as they
worked prior to this commit:

/<version_slug>
Subdomain:  302 to /<default_lang>/<version_slug>/
RTD domain: 404

/<lang_slug>
Subdomain:  404
RTD domain: 404

This commit changes the redirect behavior as follows:

/<version_slug>
Subdomain:  302 to /<default_lang>/<version_slug>/
RTD domain: 302 to /<default_lang>/<version_slug>/

/<lang_slug>
Subdomain:  302 to /<lang_slug>/<default_version>/
RTD domain: 302 to /<lang_slug>/<default_version>/

/<nonexistent_slug>
Subdomain:  404
RTD domain: 404
Add redirect_lang_slug() view. First of new views to refactor
redirect logic out of urls.py and serve_docs() view and into
separate redirect views.

Only works for /docs/<project_slug>/<lang_slug> views. Doesn't
work for subdomain views.
redirect_lang_slug() will redirect to either:
    subdomain URL -> pip.readthedocs.org/en/latest/
OR
    RTD URL -> readthedocs.org/docs/pip/en/latest/

In redirect_lang_slug(), the call to reverse(serve_docs, **kwargs)
determines which URL to redirect to.

The function default_version_kwargs() sets up kwargs for default view,
and includes 'project_slug' key if redirecting to RTD URL. If redirecting
to subdomain URL, it doesn't include 'project_slug'.
All redirect logic is now handled in redirect_* views.
@ericholscher

Copy link
Copy Markdown
Member

Awesome. I will take a look at this today. Thanks :)

ericholscher added a commit that referenced this pull request Nov 26, 2013
@ericholscher
ericholscher merged commit aa13733 into readthedocs:master Nov 26, 2013
@astrofrog

Copy link
Copy Markdown

@toffer @ericholscher - just for information, when is this likely to be present in the 'live' version of RTD?

@toffer

toffer commented Dec 9, 2013

Copy link
Copy Markdown
Member Author

@astrofrog It's already been merged into master, which means it's almost definitely live right now. (@ericholscher can chime in here, if it isn't.)

Unfortunately, my changes don't change the way RTD handles redirects the way you are hoping they do. I'm going to go comment on your PR (astropy/astropy#1841) with more details.

@toffer
toffer deleted the refactor-docs-url-routing branch February 14, 2014 17:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants