I wish :download: would keep the paths, not use /_downloads

[shimizukawa]

I often have a setup where talks/foo/index.rst says :download:slides.pdf. Moving all of those into /_downloads, with "uniquefied" names, seems unnecessary me -- I put the pdf in that subdirectory on purpose, it is very much related to the other content in that directory, and I wish its URL could just be /talks/foo/slides.pdf.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/823
• Originally reported by: Anonymous
• Originally created at: 2011-11-16T04:40:18.126

[shimizukawa]

From Richard Wall on 2014-10-23 09:40:33+00:00

We have the same problem with multiple downloadable Vagrantfile and Dockerfile s in our documentation. I'd love to see this resolved. The filename is significant in both those cases.
See https://github.com/ClusterHQ/flocker/pull/897/files#r19267218

[georgmu]

I have a similar problem.

I want to reference a download file (which is also referenced from a file via :download: syntax) from the sidebar. The sidebar does not allow access to lookup the filename after the change in #2720.

Before #2720, I could reference the download file from the _downloads directory. Since the hash introduced in #2720 is the absolute path (not relative to the document root), the hash changes from machine to machine and there is no stable way to "guess" the hash.

Best would be to have a stable file location. The option to have a stable location like requested in this ticket would solve my problem too.

[brechtm]

I second @georgmu's remark. It makes sense to have downloads accessible from a descriptive URL instead of one with hash in it. I consider the new behavior a regression since download URLs used to be stable.

[mgeier]

I also found the :download: role insufficient.

For the case where the file in question is managed by Git (i.e. it's not auto-generated), I came up with a work-around.
I'm using a custom role (gh-link) that, instead of linking to a copy of the file in _downloads/, it directly links to the source file on Github (using the appropriate version):

try:
    from subprocess import check_output
    release = check_output(['git', 'describe', '--tags', '--always'])
    release = release.decode().strip()
except Exception:
    release = '<unknown>'

github_url = 'https://github.com/user/repo'
blob_url = github_url + '/blob/' + release


def gh_link_role(rolename, rawtext, text, lineno, inliner,
                 options={}, content=()):
    from docutils import nodes, utils
    base_url = blob_url + '/path/to/doc/%s'
    text = utils.unescape(text)
    full_url = base_url % text
    pnode = nodes.reference(internal=False, refuri=full_url)
    pnode += nodes.literal(text, text, classes=['file'])
    return [pnode], []


def setup(app):
    app.add_role('gh-link', gh_link_role)

Of course this doesn't have to be Github, it would work with any other hoster as well.

It can be used like this:

... have a look at the file :gh-link:`my-file.pdf`.

Of course this is not the same behavior as the :download: role, but I prefer linking to the original source of the file instead of some copy of the file.

[red8888]

I asked this question on SO: https://stackoverflow.com/questions/70158364/how-can-i-change-the-file-path-of-files-referenced-via-the-download-role

This user had a pretty decent workaround: https://stackoverflow.com/users/7861581/john-hen

In this particular case we can (ab)use html_extra_path, adding this in conf.py
html_extra_path = ['../myproject/myfile.json']

and refer to the file with a regular hyperlink:
Link to file for reference `myfile.json <myfile.json>`_.