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 

9# Standard libraries 

10from unittest.mock import MagicMock 

11 

12# Third party libraries 

13import pytest 

14from hdl_registers.register_list import RegisterList 

15 

16# First party libraries 

17from tsfpga.module import BaseModule 

18from tsfpga.module_documentation import ModuleDocumentation 

19from tsfpga.system_utils import create_file 

20 

21# pylint: disable=redefined-outer-name 

22 

23 

24@pytest.fixture 

25def module_documentation(tmp_path): 

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

27 module_documentation_object = ModuleDocumentation(module) 

28 

29 data = """\ 

30-- ------------------------------------------------------------------------------------------------- 

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

32-- ------------------------------------------------------------------------------------------------- 

33-- Dummy from hest.vhd. 

34-- ------------------------------------------------------------------------------------------------- 

35 

36""" 

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

38 

39 return module_documentation_object 

40 

41 

42def test_documentation_header_with_no_overview_and_no_registers(module_documentation): 

43 rst = module_documentation.get_rst_document() 

44 

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

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

47 

48 assert "Register interface" not in rst 

49 

50 

51def test_documentation_header_with_overview_and_registers(module_documentation): 

52 # pylint: disable=protected-access 

53 module = module_documentation._module 

54 module._registers = MagicMock(spec=RegisterList) 

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

56 

57 data = "Dummy from apa.rst." 

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

59 

60 rst = module_documentation.get_rst_document() 

61 

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

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

64 

65 assert "Dummy from apa.rst" in rst 

66 

67 assert "Register interface" in rst 

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

69 

70 

71def test_submodule_documentation_with_file_exclude(module_documentation): 

72 data = """\ 

73-- ------------------------------------------------------------------------------------------------- 

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

75-- ------------------------------------------------------------------------------------------------- 

76-- Dummy from excluded.vhd. 

77-- ------------------------------------------------------------------------------------------------- 

78 

79""" 

80 # pylint: disable=protected-access 

81 excluded_vhd = create_file( 

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

83 ) 

84 

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

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

87 

88 rst = module_documentation.get_submodule_rst( 

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

90 ) 

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

92 

93 

94def test_submodule_documentation_with_folder_exclude(module_documentation): 

95 data = """\ 

96-- ------------------------------------------------------------------------------------------------- 

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

98-- ------------------------------------------------------------------------------------------------- 

99-- Dummy from excluded.vhd. 

100-- ------------------------------------------------------------------------------------------------- 

101 

102""" 

103 # pylint: disable=protected-access 

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

105 

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

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

108 

109 rst = module_documentation.get_submodule_rst( 

110 heading_character="-", 

111 heading_character_2="_", 

112 exclude_module_folders=["rtl"], 

113 ) 

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

115 

116 

117def test_include_sim_but_not_test_folder(module_documentation): 

118 data = """\ 

119-- ------------------------------------------------------------------------------------------------- 

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

121-- ------------------------------------------------------------------------------------------------- 

122-- Dummy from bfm.vhd. 

123-- ------------------------------------------------------------------------------------------------- 

124 

125""" 

126 # pylint: disable=protected-access 

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

128 

129 data = """\ 

130-- ------------------------------------------------------------------------------------------------- 

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

132-- ------------------------------------------------------------------------------------------------- 

133-- Dummy from tb.vhd. 

134-- ------------------------------------------------------------------------------------------------- 

135 

136""" 

137 # pylint: disable=protected-access 

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

139 

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

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

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

143 

144 rst = module_documentation.get_submodule_rst( 

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

146 ) 

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

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