Links to API doc in python tutorials

[emmanuelle]

Not sure whether this issue should be here or in ploty.py, since it depends on the solution.

It would be nice to have links to the API doc https://plot.ly/python-api-reference/ in the code blocks of the Python tutorials, for the classes and functions of plotly.py. This is something that projects using sphinx-gallery do, see for example https://scikit-learn.org/stable/auto_examples/plot_johnson_lindenstrauss_bound.html#sphx-glr-auto-examples-plot-johnson-lindenstrauss-bound-py or https://scikit-image.org/docs/stable/auto_examples/color_exposure/plot_regional_maxima.html#sphx-glr-auto-examples-color-exposure-plot-regional-maxima-py.

For a list of objects which are in the API doc, one can use the objects.inv generated when building the documentation of plotly.py (when doing "make html" in the apidoc directory, the file is in apidoc/_build/html/objects.inv). This file is an index of objects and doc pages, it is a zipped format but a human-readable version can be obtained from

python3 -m sphinx.ext.intersphinx objects.inv

Possible solutions :

• adding a javascript script to generate the links
• or patching nbconvert to generate the links when building the html pages from the md files.

[nicolaskruchten]

Thanks for recording this! I definitely agree and I wonder if we couldn’t use jupytext -- pipe with a custom little script that replaces certain patterns in Markdown with the appropriate MD link syntax? Or maybe that argument just processes Python cells and we can write another kind of preprocess or that would run before the nbconvert step?

[nicolaskruchten]

That said, it would be pretty trivial to write a tiny Javascript thing that looks for inline-code tags (I.e. inline backtick-delimited text in the source Markdown) that start with “go.” or “px.” and wraps them in links if their immediate DOM parent isn’t already a link.

[nicolaskruchten]

This is a not-too-brittle POC that doesn't check the parent tag but easily could:

$(".tutorial-content code").each(function() {
  var txt = $(this).text();
  if(/px\.([a-z]*)$/.test(txt)) {
    $(this).wrap($("<a>").attr("href", txt.replace(/px\.([a-z]*)$/, 
      "https://plot.ly/python-api-reference/generated/plotly.express.$1.html")));
  } 
})

[emmanuelle]

Thanks for the Javascript proof of concept!

As for jupytext, I'd love to use it but I don't think we can generate links in code blocks in the markdown files, since I would not expect the generation of ipynb files and their execution to go well... Pinging @mwouts here to know whether this discussion should be continued on the jupytext repo... but I don't think this is an appropriate solution here. But maybe we could write a script which would process the generated ipynb file?

I've also opened an issue in the nbconvert repo jupyter/nbconvert#1155 to discuss the interest of doing this with nbconvert.

[mwouts]

Hi @emmanuelle , @nicolaskruchten , this is an interesting use case. As far as I know Jupyter code cells can't have links, so I think adding the link when post-processing the HTML file as in your POC above is probably the way to go!