Problem

Hi! I have developed a few packages, let's call them package_a and package_b for simplicity. What I'd like to do is import some members from package_b into package_a and then generate the docs for package_a, however, I can't get that to work.

In reality, the two packages are completely separate (i.e. developed in separate private repositories), but I can't even get the docs to work if they were both in the same repository.

Example

Folder structure:

.
├── docs
│   ├── index.md
│   └── mkdocs.yml
└── src
    ├── package_a
    │   └── __init__.py
    └── package_b
        └── __init__.py

mkdocs.yaml file:

site_name: My Awesome Packages
docs_dir: .
site_dir: ../site
remote_branch: gh-pages
nav:
  - Home: index.md
theme:
  name: material
  palette:
    # Palette toggle for light mode
    - scheme: default
      primary: teal
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Palette toggle for dark mode
    - scheme: slate
      primary: teal
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
plugins:
- search
- same-dir
- mkdocstrings:
    handlers:
      python:
        paths: [../src]
        import:
        - https://docs.python.org/3/objects.inv
        options:
          filters:
          - "!^_[^_]"
          - "!__version__"
          - "!__all__"
          heading_level: 1
          show_root_heading: true
          show_category_heading: true
          merge_init_into_class: true
          show_if_no_docstring: true
          separate_signature: true
          group_by_category: true
          members_order: alphabetical
          annotations_path: brief
          show_signature_annotations: true
watch:
- ../src
- .

Installed dependencies (some of them are unused in this example, but I use it in my full use case):

mkdocs==1.4.2
mkdocs-gen-files==0.4.0
mkdocs-literate-nav==0.5.0
mkdocs-material==9.0.2
mkdocs-same-dir==0.1.2
mkdocs-section-index==0.3.4
mkdocstrings==0.19.1
mkdocstrings-python==0.8.3

The contents of docs/index.md:

# Docs
::: package_a

The contents of my packages:

# src/package_a/__init__.py
"""Package A - does stuff"""
from package_b import bar
def foo(x: int) -> str:
    return str(x)
__all__ = ["foo", "bar"]
# src/package_b/__init__.py
"""Package B - does some other stuff"""
def bar(x: str) -> int:
    return int(x)
__all__ = ["bar"]

What the docs page looks like:

Ideally, I'd like the page to show the documentation for both foo and bar.

What I tried

I tried looking through the code and I found that changing this line to have external=True seems to work, although I'm not sure if it doesn't break anything else:

Is there a more "proper" way to achieve the same thing? Thanks!