Coverage for tsfpga/test/test_module_documentation.py: 100%

1# -------------------------------------------------------------------------------------------------- 

2# Copyright (c) Lukas Vik. All rights reserved. 

3# 

4# This file is part of the tsfpga project, a project platform for modern FPGA development. 

5# https://tsfpga.com 

6# https://github.com/tsfpga/tsfpga 

7# -------------------------------------------------------------------------------------------------- 

8 

9from unittest.mock import MagicMock 

10 

11import pytest 

12from hdl_registers.register_list import RegisterList 

13 

14from tsfpga.module import BaseModule 

15from tsfpga.module_documentation import ModuleDocumentation 

16from tsfpga.system_utils import create_file 

17 

18 

19@pytest.fixture 

20def module_documentation(tmp_path): 

21 module = BaseModule(path=tmp_path / "apa", library_name="apa") 

22 module_documentation_object = ModuleDocumentation(module) 

23 

24 data = """\ 

25-- ------------------------------------------------------------------------------------------------- 

26-- Copyright (c) Lukas Vik. All rights reserved. 

27-- ------------------------------------------------------------------------------------------------- 

28-- Dummy from hest.vhd. 

29-- ------------------------------------------------------------------------------------------------- 

30 

31""" 

32 create_file(module.path / "src" / "hest.vhd", contents=data) 

33 

34 return module_documentation_object 

35 

36 

37def test_documentation_header_with_no_overview_and_no_registers(module_documentation): 

38 rst = module_documentation.get_rst_document() 

39 

40 assert "\nhest.vhd\n--------" in rst 

41 assert "Dummy from hest.vhd." in rst 

42 

43 assert "Register interface" not in rst 

44 

45 

46def test_documentation_header_with_overview_and_registers(module_documentation): 

47 # ruff: noqa: SLF001 

48 module = module_documentation._module 

49 module._registers = MagicMock(spec=RegisterList) 

50 module._registers.register_objects = MagicMock(spec=list) 

51 

52 data = "Dummy from apa.rst." 

53 create_file(module.path / "doc" / "apa.rst", contents=data) 

54 

55 rst = module_documentation.get_rst_document() 

56 

57 assert "\nhest.vhd\n--------" in rst 

58 assert "Dummy from hest.vhd." in rst 

59 

60 assert "Dummy from apa.rst" in rst 

61 

62 assert "Register interface" in rst 

63 assert ":download:`separate HTML page <apa_regs.html>`" in rst 

64 

65 

66def test_submodule_documentation_with_file_exclude(module_documentation): 

67 data = """\ 

68-- ------------------------------------------------------------------------------------------------- 

69-- Copyright (c) Lukas Vik. All rights reserved. 

70-- ------------------------------------------------------------------------------------------------- 

71-- Dummy from excluded.vhd. 

72-- ------------------------------------------------------------------------------------------------- 

73 

74""" 

75 

76 excluded_vhd = create_file( 

77 module_documentation._module.path / "rtl" / "excluded.vhd", contents=data 

78 ) 

79 

80 rst = module_documentation.get_submodule_rst(heading_character="-", heading_character_2="_") 

81 assert "Dummy from excluded.vhd." in rst 

82 

83 rst = module_documentation.get_submodule_rst( 

84 heading_character="-", heading_character_2="_", exclude_files={excluded_vhd} 

85 ) 

86 assert "Dummy from excluded.vhd." not in rst 

87 

88 

89def test_submodule_documentation_with_folder_exclude(module_documentation): 

90 data = """\ 

91-- ------------------------------------------------------------------------------------------------- 

92-- Copyright (c) Lukas Vik. All rights reserved. 

93-- ------------------------------------------------------------------------------------------------- 

94-- Dummy from excluded.vhd. 

95-- ------------------------------------------------------------------------------------------------- 

96 

97""" 

98 

99 create_file(module_documentation._module.path / "rtl" / "excluded.vhd", contents=data) 

100 

101 rst = module_documentation.get_submodule_rst(heading_character="-", heading_character_2="_") 

102 assert "Dummy from excluded.vhd." in rst 

103 

104 rst = module_documentation.get_submodule_rst( 

105 heading_character="-", 

106 heading_character_2="_", 

107 exclude_module_folders=["rtl"], 

108 ) 

109 assert "Dummy from excluded.vhd." not in rst 

110 

111 

112def test_include_sim_but_not_test_folder(module_documentation): 

113 data = """\ 

114-- ------------------------------------------------------------------------------------------------- 

115-- Copyright (c) Lukas Vik. All rights reserved. 

116-- ------------------------------------------------------------------------------------------------- 

117-- Dummy from bfm.vhd. 

118-- ------------------------------------------------------------------------------------------------- 

119 

120""" 

121 

122 create_file(module_documentation._module.path / "sim" / "bfm.vhd", contents=data) 

123 

124 data = """\ 

125-- ------------------------------------------------------------------------------------------------- 

126-- Copyright (c) Lukas Vik. All rights reserved. 

127-- ------------------------------------------------------------------------------------------------- 

128-- Dummy from tb.vhd. 

129-- ------------------------------------------------------------------------------------------------- 

130 

131""" 

132 

133 create_file(module_documentation._module.path / "test" / "tb.vhd", contents=data) 

134 

135 rst = module_documentation.get_submodule_rst(heading_character="-", heading_character_2="_") 

136 assert "Dummy from bfm.vhd." in rst 

137 assert "Dummy from tb.vhd." not in rst 

138 

139 rst = module_documentation.get_submodule_rst( 

140 heading_character="-", heading_character_2="_", exclude_module_folders=["sim"] 

141 ) 

142 assert "Dummy from bfm.vhd." not in rst 

143 assert "Dummy from tb.vhd." not in rst