24

I have some code and data samples I copy to _static directory and I would like to link to those files in documentation, something like:

.. _pca-run.py: _static/example.data

But the problem is that sphinx does not create a proper relative link to this file, but just copies the values as it is. So for nested files where _static is not in the same directory links do not work.

Mitar
  • 6,756
  • 5
  • 54
  • 86
  • 3
    Seems there is a ``:download:`` role: http://stackoverflow.com/questions/2921724/include-a-text-file-as-is-in-python-sphinx-docs – Mitar Dec 12 '11 at 14:38

2 Answers2

20

What you want is the :download: text role. (as Mitar mentioned in his comment).

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

Using this will tell Sphinx to copy the given file to a "_downloads" directory and create a hyperlink to it. This was originally intended to be used for downloadable files, like perhaps PDFs (in html output) or tarballs, or whatever. It works just fine for any other non-ReST file though.

If you really wanted, you could write an extension to do this, but I've never seen a need to, since :download: does exactly what I want.

phoenix
  • 7,988
  • 6
  • 39
  • 45
Kevin Horn
  • 4,167
  • 28
  • 30
  • But ``:download:`` is very verbose. If you want to use it multiple times, it gets tiresome. – Mitar Dec 24 '11 at 06:15
  • Are you aware of any role that works like `:download:` but accepts wildcards (or `glob` patterns)? – unode Sep 24 '12 at 15:39
  • @Unode: I'm not sure I understand why you would want to do that, but you'd probably have to create your own extension. It's not that hard though. See [sphinx-contrib](https://bitbucket.org/birkenfeld/sphinx-contrib/) for a bunch of examples. – Kevin Horn Oct 19 '12 at 15:17
  • @KevinHorn I want to automatically have a list of download links to all files that are in a certain folder and match a certain pattern, say: `*.doc` – unode Oct 19 '12 at 23:11
  • @Unode: I think you'd need to write your own extension for that. – Kevin Horn Oct 23 '12 at 20:41
10

Just find the right answer to this for images: preprend the path of the target file with /. For images referenced from an automodule

.. image:: some_file.png

will refer to the file some_file.png relative to the python file currently being processed, while

.. image:: /some_file.png

will refer to the file some_file.png relative to the location of the conf.py. This way, there is no need to pollute the source hierarchy with images.

Raffi
  • 3,068
  • 31
  • 33
  • If you separate `source` and `build` directories, you need to do the same. It means Sphinx does not look for the relative location of `conf.py`, but `html_static_path` variable inside `conf.py`. – Eray Erdin Oct 20 '18 at 10:41