Coverage for src/mkdocstrings_handlers/shell/_internal/handler.py: 47.06%

1# This module implements a handler for shell scripts and shell libraries. 

2 

3from __future__ import annotations 

4 

5from pathlib import Path 

6from typing import TYPE_CHECKING, Any, ClassVar 

7 

8from mkdocs.exceptions import PluginError 

9from mkdocstrings import BaseHandler, CollectionError, CollectorItem, get_logger 

10from shellman import DocFile 

11from shellman.templates.filters import FILTERS 

12 

13from mkdocstrings_handlers.shell._internal.config import ShellConfig, ShellOptions 

14 

15if TYPE_CHECKING: 

16 from collections.abc import Mapping, MutableMapping 

17 

18 from mkdocs.config.defaults import MkDocsConfig 

19 from mkdocstrings import HandlerOptions 

20 

21 

22_logger = get_logger(__name__) 

23 

24 

25class ShellHandler(BaseHandler): 

26 """The Shell handler class.""" 

27 

28 name: ClassVar[str] = "shell" 

29 """The handler's name.""" 

30 

31 domain: ClassVar[str] = "shell" 

32 """The cross-documentation domain/language for this handler.""" 

33 

34 enable_inventory: ClassVar[bool] = False 

35 """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file.""" 

36 

37 fallback_theme: ClassVar[str] = "material" 

38 """The theme to fallback to.""" 

39 

40 def __init__(self, config: ShellConfig, base_dir: Path, **kwargs: Any) -> None: 

41 super().__init__(**kwargs) 

42 self.config = config 

43 """The handler configuration.""" 

44 self.base_dir = base_dir 

45 """The base directory for the handler.""" 

46 self.global_options = config.options 

47 """The global options for the handler.""" 

48 

49 def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions: 

50 """Get the combined (global and local) options.""" 

51 extra = {**self.global_options.get("extra", {}), **local_options.get("extra", {})} 

52 options = {**self.global_options, **local_options, "extra": extra} 

53 try: 

54 return ShellOptions.from_data(**options) 

55 except Exception as error: 

56 raise PluginError(f"Invalid options: {error}") from error 

57 

58 def collect(self, identifier: str, options: ShellOptions) -> CollectorItem: # noqa: ARG002 

59 """Collect data from a shell script/library.""" 

60 script_path = self.base_dir / identifier 

61 try: 

62 return DocFile(str(script_path)) 

63 except FileNotFoundError as error: 

64 raise CollectionError(f"Could not find script '{script_path}'") from error 

65 

66 def render(self, data: CollectorItem, options: ShellOptions) -> str: 

67 """Render the collected data.""" 

68 heading_level = options.heading_level 

69 template = self.env.get_template("script.html.jinja") 

70 return template.render( 

71 config=options, 

72 filename=data.filename, 

73 script=data.sections, 

74 heading_level=heading_level, 

75 ) 

76 

77 def update_env(self, config: MkDocsConfig) -> None: # noqa: ARG002 

78 """Update the Jinja environment.""" 

79 self.env.trim_blocks = True 

80 self.env.lstrip_blocks = True 

81 self.env.keep_trailing_newline = False 

82 self.env.filters.update(FILTERS) 

83 

84 

85def get_handler( 

86 *, 

87 handler_config: MutableMapping[str, Any], 

88 tool_config: MkDocsConfig, 

89 **kwargs: Any, 

90) -> ShellHandler: 

91 """Simply return an instance of `ShellHandler`. 

92 

93 Parameters: 

94 handler_config: The handler configuration. 

95 tool_config: The tool (SSG) configuration. 

96 **kwargs: Keyword arguments for the base handler constructor. 

97 

98 Returns: 

99 An instance of the handler. 

100 """ 

101 base_dir = Path(tool_config.config_file_path or "./mkdocs.yml").parent 

102 return ShellHandler(config=ShellConfig(**handler_config), base_dir=base_dir, **kwargs)