update docs with current download roles

[JessicaS11]

The current docs for using the jupyter-sphinx download roles are outdated. I eventually tracked down the correct syntax as {nb-download} (from its usage in MyST-NB) with the file extension required.

I'd be happy to submit a PR to update the docs.

[akhmerov]

Thanks, I would be thankful for a PR! I don't quite understand the issue though: the docs example seems to work. What exactly is the outdated part?

[JessicaS11]

Perhaps my implementation isn't quite right then. I was trying to add a download link to some notebooks rendered (using MyST-NB) on ReadTheDocs. I installed jupyter-sphinx as a dependency, added jupyter-sphinx to my extensions in conf.py, and then tried to use the role in one of the Jupyter Notebooks to enable automatic downloading of the file. No matter what role syntax I used, Sphinx issued either a warning or error that it couldn't find the role. It was only after I switched to {nb-download} and included the .ipynb file extension that I stopped getting the errors/warnings. The commit where I first try to add this is here, with subsequent commits to play with role syntax and test the builds on readthedocs until I got some working download links (which appear differently than the one in the jupyter-sphinx docs).

[akhmerov]

Looking at your PR, it seems likely that you are using entirely myst-nb for execution and download. Why is jupyter-sphinx involved at all?

[JessicaS11]

As I searched, jupyter-sphinx was the only place I could find any docs on adding download links and the roles to do so. It sounds like I accidentally landed on the myst-nb role instead (which I couldn't find via keyword searching). I am curious why Sphinx couldn't find the jupyter-sphinx directives though.

[moorepants]

I'm getting warnings for this too. I have this in differentiation.rst:

.. note::

   You can download this example as a Python script:
   :jupyter-download:script:`differentiation` or Jupyter Notebook:
   :jupyter-download:notebook:`differentiation`.

And I get these warnings:

WARNING: unknown directive or role name: jupyter-download:script
WARNING: unknown directive or role name: jupyter-download:notebook

Installed packages:

(multibody-book) moorepants@nandi:learn-multibody-dynamics(master)$ conda list | grep jupyter
jupyter-sphinx            0.3.2              pyhd8ed1ab_1    conda-forge
jupyter_client            7.1.2              pyhd8ed1ab_0    conda-forge
jupyter_core              4.9.1           py310hff52083_1    conda-forge
jupyterlab_pygments       0.1.2              pyh9f0ad1d_0    conda-forge
jupyterlab_widgets        1.0.2              pyhd8ed1ab_0    conda-forge
(multibody-book) moorepants@nandi:learn-multibody-dynamics(master)$ conda list | grep sphinx
jupyter-sphinx            0.3.2              pyhd8ed1ab_1    conda-forge
pydata-sphinx-theme       0.8.0              pyhd8ed1ab_0    conda-forge
sphinx                    4.4.0              pyh6c4a22f_1    conda-forge
sphinx-autobuild          2021.3.14          pyhd8ed1ab_0    conda-forge
sphinx-togglebutton       0.2.3              pyhd3deb0d_0    conda-forge
sphinx_rtd_theme          1.0.0              pyhd8ed1ab_0    conda-forge
sphinxcontrib-applehelp   1.0.2                      py_0    conda-forge
sphinxcontrib-devhelp     1.0.2                      py_0    conda-forge
sphinxcontrib-htmlhelp    2.0.0              pyhd8ed1ab_0    conda-forge
sphinxcontrib-jsmath      1.0.1                      py_0    conda-forge
sphinxcontrib-qthelp      1.0.3                      py_0    conda-forge
sphinxcontrib-serializinghtml 1.1.5              pyhd8ed1ab_1    conda-forge

[moorepants]

Same issue here https://github.com/jupyter/jupyter-sphinx/issues/182

[12rambau]

since Sphinx 4 it's forbidden to use : character in a role. The correct syntax of the role is using a - like in jupyter-download-script which is also the way it's written in the documentation: https://jupyter-sphinx.readthedocs.io/en/latest/options.html#downloading-the-code-as-a-script

Can we consider this issue closed then?

[akhmerov]

I agree, closing.