1

I would like to add a bulleted list of download links within my toctree.

Ideally, it would look something like this:

  • Foo Example

    • download foo.py file
    • download foo.ipynb file

  • Bar Example

    • download bar.py file
    • download bar.ipynb file

I've tried:

.. toctree::

   foo
   * :download:`download foo.py file <files/foo.py>`
   * :download:`download foo.ipynb file <files/foo.ipynb>`
   bar
   * :download:`download bar.py file <files/bar.py>`
   * :download:`download bar.ipynb file <files/bar.ipynb>`

But this fails since toctree only expects references to documents:

WARNING: toctree contains reference to nonexisting document '* :download:`download foo.py file <files/foo.py>`'

The closest I've come is:

.. toctree::

   foo
   
* :download:`download foo.py file <files/foo.py>`
* :download:`download foo.ipynb file <files/foo.ipynb>`

.. toctree::

   bar

* :download:`download bar.py file <files/bar.py>`
* :download:`download bar.ipynb file <files/bar.ipynb>`

Which looks about like this:

  • Foo Example

  • download foo.py file

  • download foo.ipynb file

  • Bar Example

  • download bar.py file

  • download bar.ipynb file

This does not look great and I have many more documents in my actual toctree. Is there any way to accomplish this?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
dshanahan
  • 676
  • 5
  • 12

1 Answers1

2

Downloads are not reStructuredText documents, and cannot be entries in a toctree.

Instead you have two workarounds.

  1. Use a fully qualified HTTP URL to the download.

    .. toctree::

    https://helloworld.com/src/helloworld.py

  2. Create an intermediary .rst document that contains a link to the download, and put that document in your toctree.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • Makes sense. I did not know about the fully qualified HTTP URL option. Thanks! – dshanahan Aug 10 '20 at 20:41
  • @Matt I fingered it out by careful reading of the [`toctree` docs](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree): "You can also add external links, by giving an HTTP URL instead of a document name." – Steve Piercy Aug 24 '20 at 12:13