Coverage for C:\Repos\ekr-pylint\pylint\utils\docs.py: 21%

53 statements  

« prev     ^ index     » next       coverage.py v6.4, created at 2022-05-24 10:21 -0500

1# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html 

2# For details: https://github.com/PyCQA/pylint/blob/main/LICENSE 

3# Copyright (c) https://github.com/PyCQA/pylint/blob/main/CONTRIBUTORS.txt 

4 

5"""Various helper functions to create the docs of a linter object.""" 

6 

7from __future__ import annotations 

8 

9import sys 

10import warnings 

11from typing import TYPE_CHECKING, Any, TextIO 

12 

13from pylint.constants import MAIN_CHECKER_NAME 

14from pylint.utils.utils import get_rst_section, get_rst_title 

15 

16if TYPE_CHECKING: 

17 from pylint.lint.pylinter import PyLinter 

18 

19 

20def _get_checkers_infos(linter: PyLinter) -> dict[str, dict[str, Any]]: 

21 """Get info from a checker and handle KeyError.""" 

22 by_checker: dict[str, dict[str, Any]] = {} 

23 for checker in linter.get_checkers(): 

24 name = checker.name 

25 if name != MAIN_CHECKER_NAME: 

26 try: 

27 by_checker[name]["checker"] = checker 

28 with warnings.catch_warnings(): 

29 warnings.filterwarnings("ignore", category=DeprecationWarning) 

30 by_checker[name]["options"] += checker.options_and_values() 

31 by_checker[name]["msgs"].update(checker.msgs) 

32 by_checker[name]["reports"] += checker.reports 

33 except KeyError: 

34 with warnings.catch_warnings(): 

35 warnings.filterwarnings("ignore", category=DeprecationWarning) 

36 by_checker[name] = { 

37 "checker": checker, 

38 "options": list(checker.options_and_values()), 

39 "msgs": dict(checker.msgs), 

40 "reports": list(checker.reports), 

41 } 

42 return by_checker 

43 

44 

45def _get_checkers_documentation(linter: PyLinter) -> str: 

46 """Get documentation for individual checkers.""" 

47 result = get_rst_title("Pylint global options and switches", "-") 

48 result += """ 

49Pylint provides global options and switches. 

50 

51""" 

52 for checker in linter.get_checkers(): 

53 name = checker.name 

54 if name == MAIN_CHECKER_NAME: 

55 if checker.options: 

56 with warnings.catch_warnings(): 

57 warnings.filterwarnings("ignore", category=DeprecationWarning) 

58 for section, options in checker.options_by_section(): 

59 if section is None: 

60 title = "General options" 

61 else: 

62 title = f"{section.capitalize()} options" 

63 result += get_rst_title(title, "~") 

64 assert isinstance(options, list) 

65 result += f"{get_rst_section(None, options)}\n" 

66 result += get_rst_title("Pylint checkers' options and switches", "-") 

67 result += """\ 

68 

69Pylint checkers can provide three set of features: 

70 

71* options that control their execution, 

72* messages that they can raise, 

73* reports that they can generate. 

74 

75Below is a list of all checkers and their features. 

76 

77""" 

78 by_checker = _get_checkers_infos(linter) 

79 for checker_name in sorted(by_checker): 

80 information = by_checker[checker_name] 

81 checker = information["checker"] 

82 del information["checker"] 

83 result += checker.get_full_documentation(**information) 

84 return result 

85 

86 

87def print_full_documentation(linter: PyLinter, stream: TextIO = sys.stdout) -> None: 

88 """Output a full documentation in ReST format.""" 

89 print(_get_checkers_documentation(linter)[:-1], file=stream)