Coverage for tests/helpers.py: 100.00%

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

2 

3from __future__ import annotations 

4 

5from collections import ChainMap 

6from contextlib import contextmanager 

7from typing import TYPE_CHECKING, Any 

8 

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 import pytest 

17 from mkdocstrings import MkdocstringsPlugin 

18 

19 from mkdocstrings_handlers.python import PythonHandler 

20 

21 

22@contextmanager 

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

24 """Yield a MkDocs configuration object. 

25 

26 Parameters: 

27 request: Pytest request fixture. 

28 tmp_path: Temporary path. 

29 

30 Yields: 

31 MkDocs config. 

32 """ 

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

34 request = request._parent_request 

35 

36 params = getattr(request, "param", {}) 

37 plugins = params.pop("plugins", [{"mkdocstrings": {}}]) 

38 

39 conf = MkDocsConfig() 

40 conf_dict = { 

41 "site_name": "foo", 

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

43 "site_dir": str(tmp_path), 

44 "plugins": plugins, 

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

46 } 

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

48 mdx_configs: dict[str, Any] = dict(ChainMap(*conf_dict.get("markdown_extensions", []))) 

49 

50 conf.load_dict(conf_dict) 

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

52 

53 conf["mdx_configs"] = mdx_configs 

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

55 

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

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

58 yield conf 

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

60 

61 

62def plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin: 

63 """Return a plugin instance. 

64 

65 Parameters: 

66 mkdocs_conf: MkDocs configuration. 

67 

68 Returns: 

69 mkdocstrings plugin instance. 

70 """ 

71 return mkdocs_conf["plugins"]["mkdocstrings"] 

72 

73 

74def ext_markdown(mkdocs_conf: MkDocsConfig) -> Markdown: 

75 """Return a Markdown instance with MkdocstringsExtension. 

76 

77 Parameters: 

78 mkdocs_conf: MkDocs configuration. 

79 

80 Returns: 

81 A Markdown instance. 

82 """ 

83 return Markdown(extensions=mkdocs_conf["markdown_extensions"], extension_configs=mkdocs_conf["mdx_configs"]) 

84 

85 

86def handler(plugin: MkdocstringsPlugin, ext_markdown: Markdown) -> PythonHandler: 

87 """Return a handler instance. 

88 

89 Parameters: 

90 plugin: Plugin instance. 

91 

92 Returns: 

93 A handler instance. 

94 """ 

95 handler = plugin.handlers.get_handler("python") 

96 handler._update_env(ext_markdown) 

97 return handler # type: ignore[return-value]