Imports in __init__.py

[viktor40]

Hi, I'm using material for mkdocs together with mkdocstrings to create documentation for a python library. Because there are many subfolders in this library, some imports are added in __init__.py files to allow for shorter imports.

Example:
Take a module with the following structure package.submodule1.submodule2.example_class.ExampleClass
There is an __init__.py file in the package directory with the following import in it:
from .submodule1.submodule2.class import ExampleClass

by doing this, the user can import ExampleClass by doing:
from package import ExampleClass
which is much shorter.

How can I document this option when using mkdocstrings. For example, I am using the show_root_full_path: true option in the mkdocs.yml file. So the generated documentation has the full import in it. I would like the users to know about the shortened imports from the documentation so I would like to either show only the shortened import or both the full import and shortened import. Is this possible in any way?

[pawamoy]

Hello!

It is not clear exactly how you inject documentation into your pages, but you can:

• document this in your class docstring
• make your alias package.ExampleClass public (by listing it in __all__), and mkdocstrings-python will render it when injecting docs for package. its full path will show as package.ExampleClass

Does that help?

[viktor40]

Thanks for the quick response.

My __init__.py file in package now looks like this:

from .submodule1.submodule2.class import ExampleClass

__all__ = [
    ExampleClass,
]

However, when going to the documentation for package, or for ExampleClass, the alias is not visible.

As extra information, I used the Automatic code reference pages recipe to generate the markdown files for my API reference (although I don't think this should matter).

Below, you can also find my mkdocstring configuration in mkdocs.yml (if this matters).

  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            annotations_path: brief
            show_source: false
            show_signature: true
            show_root_toc_entry: false
            show_bases: true
            show_root_full_path: true
            show_root_members_full_path: true
            show_symbol_type_heading: true

[pawamoy]

Elements in __all__ must be strings, try this:

from .submodule1.submodule2.class import ExampleClass

__all__ = [
    "ExampleClass",
]

[viktor40]

Thanks, this indeed works. However, I have also set the following option: show_if_no_docstring: true. However, this also shows things like __all__, __author__, __title__ which are in the __init__.py file into the documentation. This makes sense I guess given the option, but would there be a way to prevent this? Example image below:

[pawamoy]

You can try to use other options like filters or members to hide some objects, and do so globally (in mkdocs.yml), or by updating the script from the recipe to add local options when generating pages.