0

In short, I have code that works but if I make a slight tweak, some things fall apart and I can't seem to figure out why. I'm hoping someone more experienced than me can give me a few Sphinx pointers. I've searched and haven't seen anything like this issue posted before.

Thing that works

I have package my_pkg that contains module mod that contains a number of classes and functions.

If I use the following line in my conf.py

sys.path.insert(0, os.path.abspath('../my_pkg'))

and one of my .rst files contains the following

.. automodule:: mod

.. autoclass:: mod.classA
   :members:

.. autofunction:: mod.functionA

.. autoclass:: mod.classB
   :members:

then when I run my documentation everything works! However, these render the call signatures in the output documentation as mod.classA (for instance) and I'd rather they render as my_pkg.mod.classA.

Thing that doesn't work

To make this change, I thought I should remove pkg from conf.py like so

sys.path.insert(0, os.path.abspath('../my_pkg'))

and then change my .rst file to start looking from pkg like the following:

.. automodule:: my_pkg.mod

.. autoclass:: my_pkg.mod.classA
   :members:

.. autofunction:: my_pkg.mod.functionA

.. autoclass:: my_pkg.mod.classB
   :members:

If I do this, the automodule directive doesn't pick up on anything and therefore doesn't show my module's docstring (I don't get any warnings about autodoc being unable to find pkg.mod, so I find this bizarre). The output for

.. autoclass:: my_pkg.mod.classA
   :members:

is simply alias of my_pkg.mod.... even though that's wrong. Despite this, the "source" button in the class signature correctly links to the code for that class. Finally, the remaining function and class render precisely as I want them to. It just appears Sphinx really doesn't want to document this module or classA for some reason.

This problem is driving me bonkers. It happens across multiple themes, so I believe it's a Sphinx issue. I've tried changing the docstring of classA to be just """foo""". I've tried moving classA around in the document so it's not the first bit of real code. I've tried renaming classA. Nothing seems to fix it and classA is always the problem.

Does anyone know why this could happen? I'm using Sphinx v4.1.1 and sphinx-rtd-theme v0.5.2 (the latest versions of both at the time of this post).

coney1
  • 1
  • 1

2 Answers2

0

Edit: my original thought was completely wrong but I've now been able to recreate the issue multiple times. mzjn is correct that I didn't provide enough context.

This issue seems to be caused by my_pkg being a mocked import. Within conf.py I had a line

autodoc_mock_imports = ['my_pkg', 'numpy', 'scipy', 'pandas']

My finding is that if I try to start documenting from the package root (i.e. my_pkg is the first argument to automodule and autoclass, as described in the section that didn't work) and my_pkg is a mocked import, Sphinx causes the issues that I described above. I had forgotten to remove my_pkg from the mock imports when changing the structure (which still doesn't really explain why this behavior exists, but at least I found how to reproduce it).

coney1
  • 1
  • 1
  • There is no rule that says that package names cannot contain underscores. There is not enough information in the question to reproduce the problem. – mzjn Jul 20 '21 at 07:57
0

You might need to define the __module__ attribute for your classes/functions, as described in another Stack Overflow post.

Kale Kundert
  • 1,144
  • 6
  • 18