Sphinx roles and directives not working in generated examples

[tsbinns]

I have a set of .py example files containing rst text blocks which I am trying to generate into a gallery of examples using sphinx-gallery. However, links for sphinx roles and directives are not being generated.

For example, I would expect ":class:my_project.my_class" in a text block to be converted to a link to this class in my documentation's API, however it remains as the raw text ":class:my_project.my_class" in the generated example files. Similarly, citations to bibiliography entries using ":footcite:" also do not render correctly. I have no issues using these roles and directives elswehere in the documentation, and there are no warnings from sphinx that the objects referenced within the example files cannot be found.

I have compared my config settings with other projects where I know these roles to be working in the generated examples, however I do not notice anything which I am obviously doing wrong. For building the documentation, I am using the following settings:

extensions = [
    "sphinx.ext.mathjax",
    "sphinx.ext.autosectionlabel",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.linkcode",
    "sphinx.ext.intersphinx",
    "numpydoc",
    "nbsphinx",
    "nbsphinx_link",
    "sphinxcontrib.bibtex",
    "sphinx_gallery.gen_gallery",
]

source_suffix = [".rst", ".md"]

sphinx_gallery_conf = {
    "examples_dirs": "../../examples",
    "gallery_dirs": "auto_examples",
}

The only thing I have noticed is that the sources of the auto_example html files have the suffix .ipynb.txt, whereas in other projects I have seen this as .rst.txt, e.g. build/html/auto_examples/plot_compute_my_example.html has source build/html/_sources/auto_examples/plot_compute_my_example.ipynb.txt. I have no idea how to specify the source files to be .rst.txt files, so I cannot test if this is what is causing the problem.

I'm really stumped with this one, so any help is greatly appreciated. Thanks!

[larsoner]

We do this all the time in MNE-Python, e.g.:

https://github.com/mne-tools/mne-python/blob/e6afe5fb64c46df50256635b74cf583d5cc92727/tutorials/intro/10_overview.py#L52

has proper links

https://mne.tools/dev/auto_tutorials/intro/10_overview.html#loading-data

Maybe it's some incompatibility or conflict with nbsphinx. Can you try disabling it to see what happens?

[drammock]

I would expect ":class:my_project.my_class" in a text block to be converted to a link to this class in my documentation's API, however it remains as the raw text ":class:my_project.my_class" in the generated example files.

Just to make sure: the rest of the text block is indeed being rendered as text, not as code comments? if the line(s) are mistakenly treated as code comments then sphinx roles won't be parsed.

[tsbinns]

Looks like there was a conflict with nbsphinx, seems to be working after removing this. Thanks for the help!

[GaelVaroquaux]

I would expect ":class:my_project.my_class" in a text block to be converted to a link to this class in my documentation's API

It should work. I believe that the proper syntax is :class:`my_project.my_class`