我正在使用 sphinx 为一个项目创建文档，其中包含一组我正在使用 sphinx-gallery 运行的示例，但是在生成的 html 文件、sphinx 角色和指令中（例如 :class:、:meth:、:attr:、:footcite :) 不能正确生成。除此之外，这些示例运行良好。
例如，笔记本文本块中的“
:class:my_project.my_class在文档的其他地方，我可以毫无问题地使用这些角色/指令，并且我生成的 API 也可以正常工作。我似乎唯一能够在笔记本中使用的是
:math:我在
conf.pyextensions = [
"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",
]
我已将我的配置设置与其他项目进行了比较，我知道这些项目不会发生此问题，并且我没有注意到我的项目设置中有任何丢失或不正确的内容。
在本地运行
make_htmlRunning 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.
如果我使用 readthedocs 构建文档，我也会遇到同样的问题，但是这里我有警告：
/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).
我尝试根据这篇文章中的信息指定安装 pandoc >= 2.14.2，但是我仍然看到此警告。然而，我在本地计算机上没有看到此警告，这一事实让我怀疑这就是原因。
sphinx_gallery_conf = {
"doc_module": ("my_project",),
"examples_dirs": "../../examples",
"gallery_dirs": "auto_examples",
"reference_url": {"my_project": None},
}
这是我正在尝试为其构建文档的包的链接：https://github.com/braindatalab/PyBispectra
万一其他人遇到这样的问题，原来问题出在
nbsphinxnbsphinx_linkpandoc我能够从依赖项/扩展中完全删除它们，并且生成文档没有任何问题。
sphinx-gallery