How can I prevent sphinx from displaying the full path to my class?

Question

I have a project structure like this:

package/
    __init__.py
    module.py

__init__.py contains:

from .module import Class

module.py contains:

class Class:
    pass

Using sphinx-apidoc -o package/docs/ package/ and sphinx-build package/docs/ package/docs/_build, the documentation for Class looks like this:

class package.module.Class

Bases: object

I'd like to have this output instead:

class package.Class

Bases: object

Or, even better, without the package name:

class Class

Bases: object

The user doesn't have to know in which file the class is defined; this information is completely irrelevant, if not confusing. Since __init__.py is importing Class directly into the package's namespace, users will import this class as from package import Class, not as from package.module import Class, and I want the docs to reflect that.

Is there a way to have sphinx output the path relative to the package's namespace?

Similar questions: https://stackoverflow.com/q/25276164/407651, https://stackoverflow.com/q/29385564/407651 — mzjn, Sep 17 '17 at 11:28
@mzjn Both of those ask about removing the module names from the table of contents; but I guess the solution _"write your own apidoc"_ also applies to my question? Is that really the only way? I find it hard to believe that such a commonly used documentation generator has no _"display the useful information instead of the useless information"_ switch. — Aran-Fey, Sep 17 '17 at 11:41
Did you look at https://stackoverflow.com/a/42739816/407651? Seems promising (but I haven't tried it). — mzjn, Sep 17 '17 at 11:42
@mzjn Yes, but as far as I can tell, it only supports templates for packages and modules. I may have missed something (I only started learning about sphinx yesterday), but the module template contains this: `{% for item in classes %} {{ item }}`, so I don't think it allows me to customize how classes are rendered. — Aran-Fey, Sep 17 '17 at 11:49
AFAICT, sphinx-apidoc recursively looks for Python modules and packages in a "naive" way. If you import something in the package's `__init__.py`, sphinx-apidoc does not recognize that. — mzjn, Sep 17 '17 at 12:37
a quick and _UGLY_ solution would be to post-process the generated files by applying regex replacements on a directory tree, something along [these](https://gist.github.com/elFua/29f641b9f0f3f10ddd3ec98b6c4f8d5b) lines — ccpizza, Aug 23 '18 at 18:15
Did you try changing the class' `__module__` value? E.g. `Class.__module__ = 'package'`. That will have also other side-effects, but in general, I guess it _could_ work. — zvone, Oct 09 '20 at 22:43
Does this answer your question? [Sphinx apidoc - don't print full path to packages and modules](https://stackoverflow.com/questions/25276164/sphinx-apidoc-dont-print-full-path-to-packages-and-modules) — Christopher Peisert, Oct 29 '20 at 18:12
I have seen this done by creating a bunch of "fake" modules for sphinx to document. This gives you tight control over the tree hierarchy in sphinx. Keep in mind that sphinx is geared to document python modules to be shared with other python developers, where things like preserving the module hierarchy is rather important. If you deviate from this use-case, it can become difficult to coerce Sphinx into doing what you need. — morphheus, Jan 17 '21 at 20:01

score 11 · Answer 1 · answered Mar 03 '21 at 15:00

11

Try adding add_module_names = False in conf.py

answered Mar 03 '21 at 15:00

Kanchan Srivastava

339
3
6

score 5 · Answer 2 · answered Mar 22 '21 at 09:55

While adding add_module_names = False (refer this answer) makes Sphinx render package.module.Class as Class, it does not help if you wanted to render package.module.Class as package.Class (i.e., document the class as part of the package namespace).

If you want Sphinx to document package.module.class as package.Class, include the following lines in the __init__.py for the package (refer this answer):

# This lets you use package.module.Class as package.Class in your code.
from .module import Class

# This lets Sphinx know you want to document package.module.Class as package.Class.
__all__ = ['Class']

How can I prevent sphinx from displaying the full path to my class?

2 Answers2