Description
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
└── __i
7BD1
nit__.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_aThe 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!