sphinx cross referencing in markdown cell?

[arsenovic]

is there a way to use inline sphinx cross references?

like

.. currentmodule:: myPackage.myModule

This is narrative text in a markdown cell, and then i  want to link to a 
specific  :class:`MyClass` object, and keep on talking.

[mgeier]

You mean in a Markdown cell in a notebook?

No, that's currently not possible. I'm planning to implement this once #36 is done (which might take a long time, probably forever).

In the meantime, you can try if it works for you to use "raw" cells: http://nbsphinx.readthedocs.io/en/latest/raw-cells.html. In raw reST cells all Sphinx features should work.

[arsenovic]

ok thanks for the info. i will keep an eye on #36 because i'd like to be able to reference classes within the markdown cells. otherwise its too cumbersome.

[mgeier]

You might also want to have a look at the documentation of music21. They use Jupyter notebooks with a custom converter that allows them to use Sphinx cross references.

Example docs page: http://web.mit.edu/music21/doc/usersGuide/usersGuide_03_pitches.html Source notebook: https://github.com/cuthbertLab/music21/blob/master/music21/documentation/source/usersGuide/usersGuide_03_pitches.ipynb

[arsenovic]

thats exactly what i was referring to. i would use it if it where included in this project or jupyter or sphinx (i dont know where it should go).

[mgeier]

If that's doing what you need, you can just use the stuff from music21.

I don't think it makes sense to include this feature in either Jupyter or Sphinx. It makes more sense to have it in an extension, like e.g. nbsphinx!

As I said, I won't implement this before #36, but if somebody else (for example you?) implements it and makes a PR, I wouldn't have to wait for that.

[mgeier]

@arsenovic If you still need this: In the meantime it is possible to link to your class documentation, but not (yet) with the reST syntax you are using.

Instead, you'll have to find out how the HTML anchor of your class is named and then use something like this in a Markdown cell:

[link to my class](my-api-docs.rst#mymodule.MyClass)

See https://nbsphinx.readthedocs.io/en/0.3.5/markdown-cells.html#Links-to-Domain-Objects.