(#1917) Fixing Flyout Links for MkDocs Projects

[sahilTakiar]

• Fix for Flyout links incorrect on Mkdocs projects #1917
• Test locally following the directions here http://docs.readthedocs.org/en/latest/install.html#installing-read-the-docs
• Not sure where / if to add a unit test for this change

[ericholscher]

Hmm. I do worry that that this will break other configurations. I believe we're appending the root path here because we need to be able to find it without requiring a specific current working directory.

There may be something in mkdocs handling of this setting that has changed, which is likely causing this. I guess my question is what breaks downstream of this?

The issue is actually the docroot getting set here: http://tracks.readthedocs.org/en/latest/readthedocs-data.js

[ericholscher]

Which is from here: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/mkdocs.py#L106 -- so we likely need to use a properly relative URL in the docroot that we pass into the template.

[ericholscher]

So we need to figure out if the docs_dir from the user is always relative, and then, we also need to generate a proper relative docs_dir for our linking purposes.

[sahilTakiar]

Hmm I see. Ok I believe docs_dir is can either be a relative or absolute path: http://www.mkdocs.org/user-guide/configuration/#docs_dir I am not entirely sure if its possible to handle absolute paths? What do you think the behavior should be in this case, throw an exception?

I see your point about the docroot value in http://tracks.readthedocs.org/en/latest/readthedocs-data.js - I will fix that also, and make sure the value of docroot is correct.

[agjohnson]

@sahilTakiar any more luck on this? Feel free to raise any other questions if you're unsure!

[sahilTakiar]

Hey, sorry for the delay on this. I looked into this some more and am still a little confused on why we can't make docs_dir relative.

Here is my current understanding of how this all works, please correct me if I am wrong:

• The docs_dir is specified in the mkdocs.yml file and is the relative path to the folder containing all the documentation files
• The current code converts this relative path into an absolute one, and then adds it to the READTHEDOCS_DATA docroot field
• Here is my understanding of how the docroot field is then accessed:
  • footer.js loads this READTHEDOCS_DATA from rtd-data.js
  • It makes an AJAX call containing the READTHEDOCS_DATA, which is routed to the footer_html method in footer_views.py
  • The footer_html takes the docroot field and passes it to get_github_url and get_bitbucket_url methods in models.py
  • Then the docroot is passed to GITHUB_URL.format (which is in constants.py)

The thing about the GITHUB_URL in constants.py is that the docroot is inserted directly into the URL; the string is: 'https://github.com/{user}/{repo}/{action}/{version}{docroot}{path}{source_suffix}'

Given that the docroot is inserted directly in the GitHub URL, why should it be an absolute path? It should always be a relative path, right? I assume the Sphinx integration must also set the docroot to a relative path, although I couldn't find the exact logic where that happens. Since Sphinx must be setting the docroot as a relative path, shouldn't mkdocs do the same thing?

This is the only place I can find where docroot is accessed.

Is my understanding correct? Or am I missing something.

[ericholscher]

Tested this locally and it works fine.

[marcelstoer]

General question: how do we find out when a PR goes live (i.e. becomes available in production)?

[agjohnson]

We don't have a procedure for this currently. We don't schedule releases and our release schedule is dependent on what time we have available. If there are any larger bug fixes, we generally try to do a release announcement however.

[marcelstoer]

I get this and I understand but again, what resource do I need to watch or to which resource do I need to subscribe to find out when this fix is available in production? Are there better options than manually checking on http://myproject.readthedocs.io every other day? After all, I'd like to verify at some point if what works locally for Eric also works for my project and its users.

[ericholscher]

We run production off of the rel branch, so once it gets merged there, it should be live.

[marcelstoer]

Thanks Eric, that's what I was looking for.