|
11 | 11 | from textwrap import dedent |
12 | 12 | from typing import TYPE_CHECKING |
13 | 13 |
|
| 14 | +import bs4 |
14 | 15 | import mkdocstrings |
15 | 16 | import pytest |
16 | 17 | from griffe import ( |
@@ -333,3 +334,117 @@ def test_specifying_inventory_base_url(handler: PythonHandler) -> None: |
333 | 334 | # Assert the URL is based on the provided base URL |
334 | 335 | msg = "Expected inventory URL to start with base_url" |
335 | 336 | assert item_url.startswith(base_url), msg |
| 337 | + |
| 338 | + |
| 339 | +def _source_labels(html: str) -> list[Path]: |
| 340 | + soup = bs4.BeautifulSoup(html, features="html.parser") |
| 341 | + labels = [] |
| 342 | + for summary in soup.find_all("summary"): |
| 343 | + if "Source code in" in summary.get_text(): |
| 344 | + code_tag = summary.find("code") |
| 345 | + assert code_tag is not None |
| 346 | + labels.append(Path(code_tag.get_text(strip=True))) |
| 347 | + return labels |
| 348 | + |
| 349 | + |
| 350 | +_BASE_CLASS = """ |
| 351 | +class Base: |
| 352 | + '''Base docstring.''' |
| 353 | +
|
| 354 | + def __init__(self) -> None: |
| 355 | + '''Init docstring.''' |
| 356 | + self.base_attribute = 0 |
| 357 | +
|
| 358 | + def base_method(self) -> None: |
| 359 | + '''Method docstring.''' |
| 360 | +""" |
| 361 | + |
| 362 | + |
| 363 | +def _write_venv_project(tmp_path: Path, *, single_module: bool) -> None: |
| 364 | + """Lay out the issue-333 scenario: an in-project virtual environment. |
| 365 | +
|
| 366 | + A `Base` class is "installed" in a `site-packages` directory relative to the |
| 367 | + current working directory, and the documented package inherits from it. |
| 368 | + """ |
| 369 | + site_packages = tmp_path / "site-packages" |
| 370 | + if single_module: |
| 371 | + site_packages.mkdir(parents=True) |
| 372 | + (site_packages / "basemod.py").write_text(dedent(_BASE_CLASS)) |
| 373 | + base_module = "basemod" |
| 374 | + else: |
| 375 | + base_pkg = site_packages / "basepkg" |
| 376 | + base_pkg.mkdir(parents=True) |
| 377 | + (base_pkg / "__init__.py").write_text(dedent(_BASE_CLASS)) |
| 378 | + base_module = "basepkg" |
| 379 | + pkg = tmp_path / "pkg" |
| 380 | + pkg.mkdir() |
| 381 | + (pkg / "__init__.py").write_text( |
| 382 | + dedent( |
| 383 | + f""" |
| 384 | + from {base_module} import Base |
| 385 | +
|
| 386 | + class Model(Base): |
| 387 | + '''Model docstring.''' |
| 388 | + """, |
| 389 | + ), |
| 390 | + ) |
| 391 | + |
| 392 | + |
| 393 | +@pytest.mark.parametrize( |
| 394 | + "handler", |
| 395 | + [ |
| 396 | + {"theme": "readthedocs"}, |
| 397 | + {"theme": {"name": "material"}}, |
| 398 | + ], |
| 399 | + indirect=["handler"], |
| 400 | +) |
| 401 | +@pytest.mark.parametrize( |
| 402 | + ("single_module", "identifier", "extra_options", "expected_label"), |
| 403 | + [ |
| 404 | + pytest.param( |
| 405 | + False, |
| 406 | + "pkg.Model", |
| 407 | + {"merge_init_into_class": True}, |
| 408 | + Path("basepkg", "__init__.py"), |
| 409 | + id="merged-init", |
| 410 | + ), |
| 411 | + pytest.param( |
| 412 | + False, |
| 413 | + "pkg.Model", |
| 414 | + {"merge_init_into_class": True, "inherited_members": True}, |
| 415 | + Path("basepkg", "__init__.py"), |
| 416 | + id="inherited-method", |
| 417 | + ), |
| 418 | + pytest.param(False, "basepkg.Base", {}, Path("basepkg", "__init__.py"), id="class-and-methods"), |
| 419 | + pytest.param(True, "pkg.Model", {"merge_init_into_class": True}, Path("basemod.py"), id="single-module"), |
| 420 | + ], |
| 421 | +) |
| 422 | +def test_no_environment_path_in_source_labels( |
| 423 | + *, |
| 424 | + tmp_path: Path, |
| 425 | + monkeypatch: pytest.MonkeyPatch, |
| 426 | + handler: PythonHandler, |
| 427 | + single_module: bool, |
| 428 | + identifier: str, |
| 429 | + extra_options: dict, |
| 430 | + expected_label: Path, |
| 431 | +) -> None: |
| 432 | + """Assert source labels never show an environment path, whatever renders them.""" |
| 433 | + _write_venv_project(tmp_path, single_module=single_module) |
| 434 | + monkeypatch.chdir(tmp_path) |
| 435 | + # `collect()` reads the search paths lazily from this attribute. |
| 436 | + handler._paths = [str(tmp_path), str(tmp_path / "site-packages")] |
| 437 | + base_module = "basemod" if single_module else "basepkg" |
| 438 | + options = handler.get_options( |
| 439 | + { |
| 440 | + "preload_modules": [base_module], |
| 441 | + "show_source": True, |
| 442 | + **extra_options, |
| 443 | + }, |
| 444 | + ) |
| 445 | + html = handler.render(handler.collect(identifier, options), options) |
| 446 | + labels = _source_labels(html) |
| 447 | + assert labels |
| 448 | + assert set(labels) == {expected_label} |
| 449 | + # The init source body is still rendered. |
| 450 | + assert "base_attribute" in html |
0 commit comments