Readthedocs.org: Download role not appearing with Sphinx 1.8

Created on 16 Oct 2018  路  8Comments  路  Source: readthedocs/readthedocs.org

Details

Expected Result

  • Generating an HTML document with working download links.

Actual Result

*Download links are missing in the HTML output.

Support
Source
picture aradi

Most helpful comment

I was looking a little more into this issue, I realized that you are using .. only :: builder_html, rtd uses a custom builder called readthedocs. So, you should use .. only :: builder_html or readthedocs. I tested this locally and it works

screenshot_2018-10-22 test chapter rtd test documentation

picture stsewd on 22 Oct 2018
👍2

All 8 comments

I can see the download links here https://readthedocs.org/projects/aradi-rtdtest/downloads/ and
screenshot_2018-10-16 test chapter rtd test documentation

stsewd picture stsewd on 16 Oct 2018

Sorry, my formulation was misleading. If you look at the generated HTML document https://aradi-rtdtest.readthedocs.io/en/latest/rtdtest.html, the links for the two files are missing, which were added via the :download: role to the RST-source. The original RST-source is:

Test chapter
============

Download button for some input file:

.. only :: builder_html

   See :download:`full input 1 <_downloads/md1/dftb_in.hsd>` and
   :download:`full input 2 <_downloads/md2/dftb_in.hsd>`

Finished.
aradi picture aradi on 17 Oct 2018

The links are relative to the current file or if you want to put absolute links, it need to begin with /

http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-download

stsewd picture stsewd on 17 Oct 2018

As the _downloads folder is in the same folder as the RST-source file (in docs/) it should work in my opinion. If I build the HTML locally using sphinx 1.8, the download links in the generated HTML appear as expected. Further the build log on Readthedocs seems also to indicate, that the :download: role was used correctly, as the referenced files are copied: 

copying downloadable files... [ 50%] _downloads/md1/dftb_in.hsd
copying downloadable files... [100%] _downloads/md2/dftb_in.hsd
aradi picture aradi on 18 Oct 2018

I guess the _downloads folder is colliding somehow with the folder from sphinx?

stsewd picture stsewd on 18 Oct 2018

I don't think so:

  • On my local system, building with Sphinx 1.8 produces the right HTML page.
  • I've renamed _downloads into _mydownloads. On my local system, it still works. On readthedocs it's still broken. Although Sphinx apparently recognizes the :download: role and the associated files
copying downloadable files... [ 50%] _mydownloads/md1/dftb_in.hsd
copying downloadable files... [100%] _mydownloads/md2/dftb_in.hsd

the appropriate links in the HTML page still do not show up.

aradi picture aradi on 19 Oct 2018

I was looking a little more into this issue, I realized that you are using .. only :: builder_html, rtd uses a custom builder called readthedocs. So, you should use .. only :: builder_html or readthedocs. I tested this locally and it works

screenshot_2018-10-22 test chapter rtd test documentation

stsewd picture stsewd on 22 Oct 2018
👍2

Works perfectly, thank you very much for your time! :smile:

aradi picture aradi on 23 Oct 2018
🎉1
Was this page helpful?
0 / 5 - 0 ratings

Related issues

enielse picture enielse  路  4Comments
cagataycali picture cagataycali  路  4Comments
humitos picture humitos  路  4Comments
krzychb picture krzychb  路  4Comments
davidfischer picture davidfischer  路  4Comments