How can I change the file path of files referenced via the download role to not use a hashed folder?

Question

I want to provide a link to a file in my project, but I want this link to be human readable and perma-ish.

Doing this:

Link to file for reference :download:`myfile.json <../myproject/myfile.json>`.

Generates a link that looks like this:

...../myproject/docs/_build/html/_downloads/b4c73f3851c188db23a20daeed2c/myfile.json

Do I have control over this? I want the link to just be this:

...../myproject/docs/_build/html/_downloads/myfile.json

I would actually prefer the link be in the root so it's just:

...../myproject/myfile.json

Answer 1

The download role does what it says in the documentation, i.e., it creates links with a unique hash. I don't see a way around it unless the implementation is changed.

But

I would actually prefer the link be in the root

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>`_.

The file is then necessarily in the root folder (of the built HTML documentation), as that's what html_extra_path does. It cannot be put in a subfolder such as _downloads.