I am creating documentation for a project using sphinx with a set of examples I am running with sphinx-gallery, however in the resulting html files, sphinx roles and directives (e.g. :class:, :meth:, :attr:, :footcite:) do not generate properly. Apart from this, the examples run fine.
For instance, ":class:my_project.my_class" in a text block of a notebook should create a link to "project.class", but it instead renders as ":class:my_project.my_class" in the html without any link. This is not only an issue for linking to my own documentation, but also for external packages using intersphinx.
Elsewhere in the documentation I am able to use these roles/directives without any issues, and the API I generate also works fine. The only one I seem to be able to use within notebooks is :math:, which does not involve generating any links.
I am using the following extensions in conf.py:
extensions = [
"sphinx.ext.mathjax",
"sphinx.ext.autosectionlabel",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
"sphinx.ext.linkcode",
"sphinx.ext.intersphinx",
"numpydoc",
"nbsphinx",
"nbspinx_link",
"sphinxcontrib.bibtex",
"sphinx_gallery.gen_gallery",
]
I have compared my config settings to other projects where I know this issue does not occur and I do not notice anything missing or incorrect in my project's settings.
Running make_html locally gives me the following output:
Running Sphinx v7.2.5
making output directory... done
Using Sphinx-Gallery to convert rst text blocks to markdown for .ipynb files.
checking bibtex cache... out of date
parsing bibtex file C:\Users\tsbin\GitHub\pybispectra\docs\source\refs.bib... parsed 19 entries
[autosummary] generating autosummary for: api.rst, cfc.rst, development.rst, examples.rst, index.rst, installation.rst, motivation.rst, tde.rst, utils.rst, waveshape.rst
[autosummary] generating autosummary for: C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.cfc.AAC.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.cfc.PAC.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.cfc.PPC.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.tde.TDE.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.utils.ResultsCFC.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.utils.ResultsTDE.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.utils.ResultsWaveShape.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.utils.SpatioSpectralFilter.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.utils.compute_fft.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.utils.compute_rank.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.utils.compute_tfr.rst, C:\Users\tsbin\GitHub\pybispectra\docs\source\generated\pybispectra.waveshape.WaveShape.rst
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/scipy/objects.inv...
loading intersphinx inventory from https://matplotlib.org/stable/objects.inv...
loading intersphinx inventory from https://numba.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://mne.tools/stable/objects.inv...
generating gallery...
generating gallery for auto_examples... [100%] plot_compute_waveshape.py
computation time summary:
- ..\..\examples\plot_compute_aac.py: 4.24 sec 0.0 MB
- ..\..\examples\plot_compute_waveshape_noisy_data.py: 4.02 sec 0.0 MB
- ..\..\examples\plot_compute_waveshape.py: 2.49 sec 0.0 MB
- ..\..\examples\plot_compute_ppc.py: 2.46 sec 0.0 MB
- ..\..\examples\plot_compute_tde.py: 1.47 sec 0.0 MB
- ..\..\examples\plot_compute_pac.py: 1.31 sec 0.0 MB
- ..\..\examples\plot_compute_pac_control_harmonics.py: 0.00 sec 0.0 MB
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 10 source files that are out of date
updating environment: [new config] 31 added, 0 changed, 0 removed
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.02s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.01s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.02s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
reading sources... [100%] waveshape
WARNING: multiple files found for the document "auto_examples/plot_compute_aac": ['auto_examples\\plot_compute_aac.ipynb', 'auto_examples\\plot_compute_aac.py', 'auto_examples\\plot_compute_aac.py.md5', 'auto_examples\\plot_compute_aac.rst']
Use 'C:\\Users\\tsbin\\GitHub\\pybispectra\\docs\\source\\auto_examples/plot_compute_aac.ipynb' for the build.
WARNING: multiple files found for the document "auto_examples/plot_compute_pac": ['auto_examples\\plot_compute_pac.ipynb', 'auto_examples\\plot_compute_pac.py', 'auto_examples\\plot_compute_pac.py.md5', 'auto_examples\\plot_compute_pac.rst']
Use 'C:\\Users\\tsbin\\GitHub\\pybispectra\\docs\\source\\auto_examples/plot_compute_pac.ipynb' for the build.
WARNING: multiple files found for the document "auto_examples/plot_compute_pac_control_harmonics": ['auto_examples\\plot_compute_pac_control_harmonics.ipynb', 'auto_examples\\plot_compute_pac_control_harmonics.py', 'auto_examples\\plot_compute_pac_control_harmonics.py.md5', 'auto_examples\\plot_compute_pac_control_harmonics.rst']
Use 'C:\\Users\\tsbin\\GitHub\\pybispectra\\docs\\source\\auto_examples/plot_compute_pac_control_harmonics.ipynb' for the build.
WARNING: multiple files found for the document "auto_examples/plot_compute_ppc": ['auto_examples\\plot_compute_ppc.ipynb', 'auto_examples\\plot_compute_ppc.py', 'auto_examples\\plot_compute_ppc.py.md5', 'auto_examples\\plot_compute_ppc.rst']
Use 'C:\\Users\\tsbin\\GitHub\\pybispectra\\docs\\source\\auto_examples/plot_compute_ppc.ipynb' for the build.
WARNING: multiple files found for the document "auto_examples/plot_compute_tde": ['auto_examples\\plot_compute_tde.ipynb', 'auto_examples\\plot_compute_tde.py', 'auto_examples\\plot_compute_tde.py.md5', 'auto_examples\\plot_compute_tde.rst']
Use 'C:\\Users\\tsbin\\GitHub\\pybispectra\\docs\\source\\auto_examples/plot_compute_tde.ipynb' for the build.
WARNING: multiple files found for the document "auto_examples/plot_compute_waveshape": ['auto_examples\\plot_compute_waveshape.ipynb', 'auto_examples\\plot_compute_waveshape.py', 'auto_examples\\plot_compute_waveshape.py.md5', 'auto_examples\\plot_compute_waveshape.rst']
Use 'C:\\Users\\tsbin\\GitHub\\pybispectra\\docs\\source\\auto_examples/plot_compute_waveshape.ipynb' for the build.
WARNING: multiple files found for the document "auto_examples/plot_compute_waveshape_noisy_data": ['auto_examples\\plot_compute_waveshape_noisy_data.ipynb', 'auto_examples\\plot_compute_waveshape_noisy_data.py', 'auto_examples\\plot_compute_waveshape_noisy_data.py.md5', 'auto_examples\\plot_compute_waveshape_noisy_data.rst']
Use 'C:\\Users\\tsbin\\GitHub\\pybispectra\\docs\\source\\auto_examples/plot_compute_waveshape_noisy_data.ipynb' for the build.
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_pac.ipynb:35: WARNING: duplicate label background, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_aac.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_pac_control_harmonics.ipynb:35: WARNING: duplicate label background, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_pac.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_ppc.ipynb:35: WARNING: duplicate label background, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_pac_control_harmonics.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_ppc.ipynb:55: WARNING: duplicate label generating data and computing fourier coefficients, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_aac.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_ppc.ipynb:272: WARNING: duplicate label references, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_pac.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_tde.ipynb:35: WARNING: duplicate label background, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_ppc.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_tde.ipynb:79: WARNING: duplicate label loading data and computing fourier coefficients, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_pac.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_waveshape.ipynb:37: WARNING: duplicate label background, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_tde.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_waveshape.ipynb:69: WARNING: duplicate label loading data and computing fourier coefficients, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_tde.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_waveshape.ipynb:392: WARNING: duplicate label references, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_ppc.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_waveshape_noisy_data.ipynb:42: WARNING: duplicate label background, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_waveshape.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\plot_compute_waveshape_noisy_data.ipynb:304: WARNING: duplicate label references, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_waveshape.ipynb
C:\Users\tsbin\GitHub\pybispectra\docs\source\motivation.rst:121: WARNING: duplicate label references, other instance in C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples/plot_compute_waveshape_noisy_data.ipynb
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying downloadable files... [100%] auto_examples/auto_examples_jupyter.zip
copying static files... done
copying extra files... done
done
writing output... [100%] waveshape
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\index.rst:24: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_pac_control_harmonics.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\index.rst:41: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_ppc.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\index.rst:58: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_aac.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\index.rst:75: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_pac.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\index.rst:92: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_tde.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\index.rst:109: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_waveshape_noisy_data.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\index.rst:126: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_waveshape.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\sg_execution_times.rst:13: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_aac.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\sg_execution_times.rst:15: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_waveshape_noisy_data.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\sg_execution_times.rst:17: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_waveshape.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\sg_execution_times.rst:19: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_ppc.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\sg_execution_times.rst:21: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_tde.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\sg_execution_times.rst:23: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_pac.py'
C:\Users\tsbin\GitHub\pybispectra\docs\source\auto_examples\sg_execution_times.rst:25: WARNING: undefined label: 'sphx_glr_auto_examples_plot_compute_pac_control_harmonics.py'
generating indices... genindex py-modindex done
copying linked files...
copying notebooks ... [100%] auto_examples/plot_compute_waveshape_noisy_data.ipynb
writing additional pages... search done
copying images... [100%] ../build/doctrees/nbsphinx/auto_examples_plot_compute_waveshape_noisy_data_8_1.png
dumping search index in English (code: en)... done
dumping object inventory... done
Sphinx-Gallery successfully executed 7 out of 7 files subselected by:
gallery_conf["filename_pattern"] = '\\\\plot'
gallery_conf["ignore_pattern"] = '__init__\\.py'
after excluding 0 files that had previously been run (based on MD5).
embedding documentation hyperlinks...
embedding documentation hyperlinks for auto_examples... [100%] sg_execution_times.html
build succeeded, 34 warnings.
The HTML pages are in build\html.
I have the same problem if I build the documentation using readthedocs, however here I have the warning:
/nbsphinx/__init__.py:1058: RuntimeWarning: You are using an unsupported version of pandoc (2.9.2.1).
Your version must be at least (2.14.2) but less than (4.0.0).
I tried to specify pandoc >= 2.14.2 be installed based on the information in this post, however I still see this warning. The fact that I do not see this warning on my local machine however makes me doubt that this is the cause.
sphinx_gallery_conf = {
"doc_module": ("my_project",),
"examples_dirs": "../../examples",
"gallery_dirs": "auto_examples",
"reference_url": {"my_project": None},
}
Here is a link to the package I am trying to build the documentation for: https://github.com/braindatalab/PyBispectra
In case anyone else ecounters an issue like this, it turns out the problem came from an incompatibility with nbsphinx and nbsphinx_link, there was nothing wrong with the pandoc installation
I was able to completely remove these from the dependencies/extensions and the documentation was generated without any problems.
GitHub issue with the sphinx-gallery developers with the solution: https://github.com/sphinx-gallery/sphinx-gallery/issues/1195