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

I have a project including a Python package as well as some Matlab code, which should all go into the same documentation created by Sphinx. The Python part of the documentation works flawlessly quite some time already - the Matlab part was added now and makes some trouble.

The data structure more or less is as follows:

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

The most relevant lines in conf.py are prob. the following:

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'

As you see, I tried both relative and absolute paths for matlab_src_dir. So far, without any difference.

The python.rst, which was created automatically by apidoc, contains:

python package
==============

.. automodule:: python
   :members:
   :undoc-members:
   :show-inheritance:

Subpackages
-----------

.. toctree::
   :maxdepth: 4

   python.subpackages

The matlab.rst was created manually and contains:

matlab package
==============

.. mat:automodule:: matlab
   :members:
   :undoc-members:
   :show-inheritance:

Subscripts
----------

.. toctree::
   :maxdepth: 4

   matlab.function_file

Thus, python.rst and matlab.rst are more or less the same but with mat:automodule for Matlab according to the documentation.

Finally, index.rst contains:

.. toctree::
   :maxdepth: 2
   
   python

.. toctree::
   :maxdepth: 2
   
   matlab

Now, when I run Sphinx' make html I receive the following error, which results in a nice Python documentation but an empty Matlab documentation:

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'

What am I missing here. Why can't Sphinx find the matlab folder with the containing m-files?

And if that should be solved, maybe a secondary question: is there any similar function as apidoc for Matlab files, so that I do not need to create all *.rst files myself?

Thank you for any hints!

BTW: I am running on Sphinx v4.4.0 under Python 3.9.7.

CodePudding user response：

Neither providing a hard-coded absolute path to matlab_src_dir nor providing os.path.abspath(relative_path) lead to success.

Thanks to Steve Piercy, who mentioned an example in the comments, I found that I should use os.path.dirname(os.path.abspath(relative_path)). As such, the errors are gone and Sphinx is working. This is interesting, because I have already tried os.path.abspath(relative_path to the parent of the package) before, which I would expect is doing the same than os.path.dirname(). Anyway, I got a working solution now.

If anybody would have an idea about the second question ("is there any similar function as apidoc for Matlab files, so that I do not need to create all *.rst files myself?") I would be really happy.