带有 Python 和 Matlab (sphinxcontrib-matlabdomain) 的 Sphinx：导入失败

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 中最相关的行是概率。以下：

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 或多或少相同，但根据 documentation.

对于 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>>\AppData\Roaming\Python\Python39\site-packages\sphinxcontrib\mat_documenters.py", line 117, in import_object
    obj = self.module = modules[self.modname]
KeyError: 'matlab'

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

如果应该解决这个问题，也许还有一个次要问题：对于 Matlab 文件是否有与 apidoc 类似的功能，这样我就不需要自己创建所有 *.rst 文件？

感谢您的任何提示！

顺便说一句：我运行在 Python 3.9.7.

下使用 Sphinx v4.4.0

Answer 1

既不提供 matlab_src_dir 的 hard-coded 绝对路径，也不提供 os.path.abspath(relative_path) 导致成功。

感谢 Steve Piercy，他在评论中提到了一个例子，我发现我应该使用 os.path.dirname(os.path.abspath(relative_path))。因此，错误消失了，Sphinx 正在运行。这很有趣，因为我之前已经尝试过 os.path.abspath(relative_path to the parent of the package)，我希望它的效果与 os.path.dirname() 相同。无论如何，我现在有了一个可行的解决方案。

如果有人对第二个问题有想法（“是否有与 apidoc 类似的函数用于 Matlab 文件，这样我就不需要自己创建所有 *.rst 文件？”）我会很高兴.

带有 Python 和 Matlab (sphinxcontrib-matlabdomain) 的 Sphinx：导入失败

Sphinx with both Python and Matlab (sphinxcontrib-matlabdomain): Import fail

python

matlab

python-sphinx