同时使用Python和Matlab的Sphinx(sphinxcontrib matlabdomain):导入失败

Question

我有一个项目，包括一个Python包和一些Matlab代码，这些代码都应该放在Sphinx创建的同一文档中。文档中的Python部分已经完美地工作了很长一段时间——现在添加了Matlab部分，这带来了一些麻烦。

数据结构大致如下：

|- python
|- modules
|- including subpackages
|- some sub-modules
|- matlab
|- scripts
|- functions
|- docs
|- source
|- conf.py
|- matlab.rst
|- python.rst
|- index.rst
|- ...

conf.py中最相关的行是prob。以下内容：

import os
import sys
# for the Python autodoc package
sys.path.insert(0, os.path.abspath('../..'))
extensions = ['sphinx.ext.napoleon', 'sphinxcontrib.matlab', 'sphinx.ext.autodoc']
# Path to the Matlab files
matlab_src_dir = '../../matlab'
#matlab_src_dir = '<<abssolute_path>>/matlab'

如您所见，我尝试了matlab_src_dir的相对路径和绝对路径。到目前为止，没有任何区别。

apidoc自动创建的python.rst包含：

python package
==============
.. automodule:: python
:members:
:undoc-members:
:show-inheritance:
Subpackages
-----------
.. toctree::
:maxdepth: 4
python.subpackages

matlab.rst是手动创建的，包含：

matlab package
==============
.. mat:automodule:: matlab
:members:
:undoc-members:
:show-inheritance:
Subscripts
----------
.. toctree::
:maxdepth: 4
matlab.function_file

因此，根据文献，python.rst和matlab.rst或多或少相同，但与Matlab的mat:automodule相同。

最后，index.rst包含：

.. toctree::
:maxdepth: 2

python
.. toctree::
:maxdepth: 2

matlab

现在，当我运行Sphinx'make html时，我收到以下错误，这导致了一个很好的Python文档，但却是一个空的Matlab文档：

WARNING: [sphinxcontrib-matlabdomain]: failed to import module 'matlab'; the following exception was raised:
Traceback (most recent call last):
File "C:Users<<username>>AppDataRoamingPythonPython39site-packagessphinxcontribmat_documenters.py", line 117, in import_object
obj = self.module = modules[self.modname]
KeyError: 'matlab'

我在这里错过了什么。为什么Sphinx找不到包含m文件的matlab文件夹？

如果这个问题应该得到解决，也许还有一个次要的问题：对于Matlab文件，有没有类似apidoc的函数，这样我就不需要自己创建所有的*.rst文件了？

谢谢你的提示！

BTW：我正在Python 3.9.7下的Sphinx v4.4.0上运行。

Answer 1

无论是提供到matlab_src_dir的硬编码绝对路径，还是提供os.path.abspath(relative_path)，都不会带来成功。

感谢Steve Piercy，他在评论中提到了一个例子，我发现我应该使用os.path.dirname(os.path.abspath(relative_path))。因此，错误已经消失，斯芬克斯正在工作。这很有趣，因为我以前已经尝试过os.path.abspath(relative_path to the parent of the package)，我希望它与os.path.dirname()做得一样。不管怎样，我现在有了一个可行的解决方案。

如果有人对第二个问题有想法("有没有类似于Matlab文件的apidoc的函数，这样我就不需要自己创建所有*.rst文件了？"(，我会非常高兴。