Sphinx结合MATLAB无法生成文档问题求助

问题情况 #

使用Sphinx为MATLAB库生成文档，执行make html无报错，但未生成任何实际文档内容，构建日志显示无待更新的源文件。

目录结构 #

|- Matlab
      |- scripts
      |- functions
|- docs
      |- source
      |- conf.py
      |- index.rst
      |- Makefile
      |- make.bat

当前conf.py配置 #

import os

extensions = [
'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinxcontrib.matlab'
]

this_dir = os.path.dirname(os.path.abspath('Matlab'))
matlab_src_dir = os.path.abspath(os.path.join(this_dir, '..'))
primary_domain = 'mat'

构建日志 #

Running Sphinx v5.0.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in _build\html.

解决步骤 #

1. 修正MATLAB源路径配置 #

当前matlab_src_dir路径计算错误，导致Sphinx无法找到MATLAB代码文件。修改conf.py中的路径配置：

import os

extensions = [
'sphinx.ext.viewcode', 'sphinx.ext.autodoc', 'sphinxcontrib.matlab'
]

# 获取conf.py所在的docs目录绝对路径
this_dir = os.path.dirname(os.path.abspath(__file__))
# 指向与docs同级的Matlab目录
matlab_src_dir = os.path.abspath(os.path.join(this_dir, '../Matlab'))
primary_domain = 'mat'

2. 配置文档生成指令 #

• 方法一：手动在index.rst中添加自动提取MATLAB函数/脚本的指令，比如针对functions目录下的模块：

.. toctree::
   :maxdepth: 2
   :caption: 函数文档

.. autofunction:: functions.your_function_name
   :members:

• 方法二：使用sphinx-apidoc自动生成rst文件，在docs目录下执行：

sphinx-apidoc -o source ../Matlab/functions

执行后会在docs/source下生成对应rst文件，再在index.rst的toctree中添加这些文件：

.. toctree::
   :maxdepth: 2
   :caption: 文档内容

   functions

3. 清理缓存后重新构建 #

执行以下命令清除旧构建缓存，再重新生成文档：

make clean
make html

4. 验证sphinxcontrib.matlab兼容性 #

确保sphinxcontrib.matlab版本与Sphinx 5.0.2兼容，可重新安装指定版本：

pip install sphinxcontrib-matlab==0.5.2

内容的提问来源于stack exchange，提问作者EAK