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 

56 data = "Dummy from apa.rst." 

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

58 

59 rst = module_documentation.get_rst_document() 

60 

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

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

63 

64 assert "Dummy from apa.rst" in rst 

65 

66 assert "Register interface" in rst 

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

68 

69 

70def test_submodule_documentation_with_file_exclude(module_documentation): 

71 data = """\ 

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

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

74-- ------------------------------------------------------------------------------------------------- 

75-- Dummy from excluded.vhd. 

76-- ------------------------------------------------------------------------------------------------- 

77 

78""" 

79 # pylint: disable=protected-access 

80 excluded_vhd = create_file( 

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

82 ) 

83 

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

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

86 

87 rst = module_documentation.get_submodule_rst( 

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

89 ) 

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

91 

92 

93def test_submodule_documentation_with_folder_exclude(module_documentation): 

94 data = """\ 

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

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

97-- ------------------------------------------------------------------------------------------------- 

98-- Dummy from excluded.vhd. 

99-- ------------------------------------------------------------------------------------------------- 

100 

101""" 

102 # pylint: disable=protected-access 

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

104 

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

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

107 

108 rst = module_documentation.get_submodule_rst( 

109 heading_character="-", 

110 heading_character_2="_", 

111 exclude_module_folders=["rtl"], 

112 ) 

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

114 

115 

116def test_include_sim_but_not_test_folder(module_documentation): 

117 data = """\ 

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

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

120-- ------------------------------------------------------------------------------------------------- 

121-- Dummy from bfm.vhd. 

122-- ------------------------------------------------------------------------------------------------- 

123 

124""" 

125 # pylint: disable=protected-access 

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

127 

128 data = """\ 

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

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

131-- ------------------------------------------------------------------------------------------------- 

132-- Dummy from tb.vhd. 

133-- ------------------------------------------------------------------------------------------------- 

134 

135""" 

136 # pylint: disable=protected-access 

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

138 

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

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

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

142 

143 rst = module_documentation.get_submodule_rst( 

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

145 ) 

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

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