Readthedocs.org: edit_uri misbehaving when using mkdocs as rendering engine

[mauroservienti]

Details

• Read the Docs project URL: https://readthedocs.org/projects/radical-documentation/
• Build URL (if applicable): —
• Read the Docs username (if applicable): mauroservienti

Actual Result

I'm trying to setup documentation for our OSS project using Read The Docs, that is much much faster compared to what we're using now. We need to have the Edit on GitHub button on every page linking directly to the markdown file in our documentation repo.

I've configured our mkdocs.yml following the documentation. However regardless of whatever configuration I use it seems that the edit_uri setting is always ignored, and the rendered documentation Edit on GitHub button links to the repo and not to the markdown document.

It seems to me that the problem lies here: https://github.com/rtfd/sphinx_rtd_theme/blob/7cd846b4fdd0e971f2c409ad9a2af24070b7b111/sphinx_rtd_theme/breadcrumbs.html#L40-L46

In which case it's a template issue. Unfortunately I have no idea how the engine works. Looking at the linked code above it seems that the logic is:

• if there is a github_url defined directly use that
• otherwise build one (this is what I expect to happen)

The problem with the above code lies in the display_github variable that is true only if github_url is defined, in with case it means that the if/else will always evaluate to true rendering only the github_url, without the full path to the document.

[mauroservienti]

I raised an issue with MkDocs first, https://github.com/mkdocs/mkdocs/issues/1472. They state on their side everything is fine. However they don’t know which version of the engine RTD is using.

[stsewd]

RTD is using mkdocs==0.15.0 on your build

ok, I was able to replicate this, going to investigate more about it.

[stsewd]

By the way, the link to Edit on GitHub on the footer works perfectly.

[stsewd]

OK, the readthedocs theme is from mkdocs itself http://www.mkdocs.org/user-guide/styling-your-docs/#readthedocs, the theme you linked is used for sphinx projects only.

This is the code that controls the Edit button for mkdocs https://github.com/mkdocs/mkdocs/blob/e5c2459fdf58e55237fef914ac67a968c68d2a3f/mkdocs/themes/readthedocs/breadcrumbs.html#L16-L25

[stsewd]

Anyway, this looks like a per page configuration https://github.com/mkdocs/mkdocs/blob/e5c2459fdf58e55237fef914ac67a968c68d2a3f/mkdocs/themes/readthedocs/breadcrumbs.html#L17

Maybe you want to check this http://www.mkdocs.org/user-guide/custom-themes/#pageedit_url and http://www.mkdocs.org/user-guide/configuration/#edit_uri. I think the rtd theme that mkdocs provide doesn't support the edit functionality with the full path on the top header (just a link to the repo).

[mauroservienti]

@stsewd thanks for the prompt response. Yes, the edit link in the footer works fine, however it’s near to undiscoverable unfortunately. Its position is not intuitive.

I’ll go back to MkDocs to investigate the template issue. In the meantime we can proceed with the migration, since the footer edit link is a good enough workaround for us.

Thanks again. Feel free to close this one.

[stsewd]

@mauroservienti let's keep this open till we can confirm this is really a limitation from mkdocs' readthedocs-theme.

[waylan]

MkDocs is currently at version 0.17.3, which does not exhibit the problem reported here. You guys will need to update to the latest version to take advantage of that fix (among many others). Note that we refactored how themes work in 0.16-0.17 (see the release notes) so you will likely need to make some changes to your code in readthedocs/doc_builder/backends/mkdocs.py.

[davidfischer]

@stsewd I don't know if you've started on this one but I've been doing some work on mkdocs @ readthedocs lately and I can take this one if you haven't already.

[stsewd]

@davidfischer I don't have any code, so feel free to take this one :)

[davidfischer]

I believe I have a fix that updates to the latest mkdocs in #4041.