Coverage for tests/conftest.py: 96.77%

1"""Configuration for the pytest test suite.""" 

2 

3from __future__ import annotations 

4 

5from collections import ChainMap 

6from typing import TYPE_CHECKING 

7 

8import pytest 

9from markdown.core import Markdown 

10from mkdocs.config.defaults import MkDocsConfig 

11 

12if TYPE_CHECKING: 

13 from collections.abc import Iterator 

14 from pathlib import Path 

15 

16 from mkdocstrings import MkdocstringsExtension, MkdocstringsPlugin 

17 

18 

19@pytest.fixture(name="mkdocs_conf") 

20def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]: 

21 """Yield a MkDocs configuration object. 

22 

23 Parameters: 

24 request: Pytest request fixture. 

25 tmp_path: Pytest temporary path fixture. 

26 

27 Yields: 

28 MkDocs configuration object. 

29 """ 

30 conf = MkDocsConfig() 

31 while hasattr(request, "_parent_request") and hasattr(request._parent_request, "_parent_request"): 

32 request = request._parent_request 

33 

34 conf_dict = { 

35 "site_name": "foo", 

36 "site_url": "https://example.org/", 

37 "site_dir": str(tmp_path), 

38 "plugins": [{"mkdocstrings": {"default_handler": "python"}}], 

39 **getattr(request, "param", {}), 

40 } 

41 # Re-create it manually as a workaround for https://github.com/mkdocs/mkdocs/issues/2289 

42 mdx_configs = dict(ChainMap(*conf_dict.get("markdown_extensions", []))) 

43 

44 conf.load_dict(conf_dict) 

45 assert conf.validate() == ([], []) 

46 

47 conf["mdx_configs"] = mdx_configs 

48 conf["markdown_extensions"].insert(0, "toc") # Guaranteed to be added by MkDocs. 

49 

50 conf = conf["plugins"]["mkdocstrings"].on_config(conf) 

51 conf = conf["plugins"]["autorefs"].on_config(conf) 

52 yield conf 

53 conf["plugins"]["mkdocstrings"].on_post_build(conf) 

54 

55 

56@pytest.fixture(name="plugin") 

57def fixture_plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: 

58 """Return a plugin instance. 

59 

60 Parameters: 

61 mkdocs_conf: MkDocs configuration object (fixture). 

62 

63 Returns: 

64 Configurated plugin instance. 

65 """ 

66 plugin = mkdocs_conf["plugins"]["mkdocstrings"] 

67 plugin.md = Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) 

68 return plugin 

69 

70 

71@pytest.fixture(name="ext_markdown") 

72def fixture_ext_markdown(plugin: MkdocstringsPlugin) -> MkdocstringsExtension: 

73 """Return a Markdown instance with MkdocstringsExtension. 

74 

75 Parameters: 

76 plugin: A configurated plugin instance. (fixture). 

77 

78 Returns: 

79 The plugin Markdown instance. 

80 """ 

81 return plugin.md # type: ignore[attr-defined]