autodoc | Doc generation on steroids

Don't use -py3. It's not required for Python 3, but enables Python 3-specific code features like annotations.

There's a page on the docs that teaches how to use extensions. The page is here: https://www.sphinx-doc.org/en/master/usage/extensions/index.html

In this page you have the following description:

A list of strings that are module names of extensions. These can be extensions coming with Sphinx (named sphinx.ext.*) or custom ones.

This tells you that sphinx.ext.* are the built-ins extensions (You can confirm that from here)

Basically when it states some kind of configuration, it refers to the conf.py file that is generated when you run sphinx-quickstart, which is a quick-setup command for sphinx in general (Might be a good read: https://www.sphinx-doc.org/en/master/usage/quickstart.html)

The root directory of a Sphinx collection of plain-text document sources is called the source directory. This directory also contains the Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your sources and builds your documentation.

Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you.

Note that, as it's built-in, it's already setupped with your sphinx project. But if you want to customize it somehow, you can use conf.py file with autodoc_* configurations (As listed here)

There are also some notes that might be useful for your case

For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly.

Thanks to @mzjin's answer in the comments: this link describes that it is possible since v0.4.

The below example is given in the link, which is exactly what I was looking for.

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.

As proposed in comment from @mzjn, I used sphinxcontrib-restbuilder for this purpose. Hyperlinks work, this is perfect for my need.

I applied it on the sphinx documentation of a public project of mine, and uploaded it on this github repo for those willing to have a look.

Click on index.rst and follow the read. There do be some glitches. The API is documented in api.rst. This is really this part that is of interest for me. I think it is nice enough.

I think the problem comes from sys.path.insert(0, os.path.abspath('..')). You're actually adding modules to the Python path, so import simulator would import modules/simulator and not modules/simulator/simulator as you would like. You should rather do:

Note: The issue has been fixed in Furo 2022.1.2.

It's definitely the theme. Probably an oversight, or even a bug, as Furo shouldn't change capitalization of identifiers and types in the API documentation. But it does, here, by applying the CSS property text-transform: uppercase.

You can override it with a custom style. In your docs folder, create a subfolder style, and in it a file custom.css with this content:

This was actually a bug and has been fixed https://github.com/sphinx-doc/sphinx/pull/9905

Ok... feeling pretty dumb about this, but it was just cause of the warnings.

Sphinx requires that the package is a fully installable package in the sense that when it is placed in the sphinx package, it should be able to compile. I had some absolute references in my import statements which caused my program to fail. As such, the actual docstrings in my program could not be pulled while the names of the classes still showed in my sphinx html.

Basically make sure your code compiles when trying to throw it in Sphinx.