Coverage for hdl_registers/about.py: 32%

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

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

3# 

4# This file is part of the hdl-registers project, an HDL register generator fast enough to run 

5# in real time. 

6# https://hdl-registers.com 

7# https://github.com/hdl-registers/hdl-registers 

8# -------------------------------------------------------------------------------------------------- 

9 

10REPOSITORY_URL = "https://github.com/hdl-registers/hdl-registers" 

11WEBSITE_URL = "https://hdl-registers.com" 

12 

13 

14def get_short_slogan() -> str: 

15 """ 

16 Short slogan used e.g. on pypi.org. 

17 Note that there seems to be an upper limit of 98 characters when rendering the slogan 

18 on pypi.org. 

19 

20 Note that this slogan should be the same as the one used in the readme and on the website below. 

21 The difference is capitalization and whether the project name is included. 

22 """ 

23 result = "An open-source HDL register interface code generator fast enough to run in real time" 

24 return result 

25 

26 

27def get_readme_rst( 

28 include_extra_for_github: bool = False, 

29 include_extra_for_website: bool = False, 

30 include_extra_for_pypi: bool = False, 

31) -> str: 

32 """ 

33 Get the complete README.rst (to be used on website and in PyPI release). 

34 RST file inclusion in README.rst does not work on GitHub unfortunately, hence this 

35 cumbersome handling where the README is duplicated in two places. 

36 

37 The arguments control some extra text that is included. This is mainly links to the 

38 other places where you can find information on the project (website, GitHub, PyPI). 

39 

40 Arguments: 

41 include_extra_for_github (bool): Include the extra text that shall be included in the 

42 GitHub README. 

43 include_extra_for_website (bool): Include the extra text that shall be included in the 

44 website main page. 

45 include_extra_for_pypi (bool): Include the extra text that shall be included in the 

46 PyPI release README. 

47 """ 

48 if include_extra_for_github: 

49 readme_rst = "" 

50 extra_rst = f"""\ 

51**See documentation on the website**: {WEBSITE_URL} 

52 

53""" 

54 elif include_extra_for_website: 

55 # The website needs the initial heading, in order for the landing page to get 

56 # the correct title. 

57 # The others do not need this initial heading, it just makes the GitHub/PyPI page 

58 # more clunky. 

59 readme_rst = """\ 

60About hdl-registers 

61=================== 

62 

63""" 

64 extra_rst = f"""\ 

65To install the Python package, see :ref:`installation`. 

66To check out the source code go to the 

67`GitHub page <{REPOSITORY_URL}>`__. \ 

68""" 

69 elif include_extra_for_pypi: 

70 readme_rst = "" 

71 extra_rst = f"""\ 

72**See documentation on the website**: {WEBSITE_URL} 

73 

74**Check out the source code on GitHub**: {REPOSITORY_URL} 

75 

76""" 

77 else: 

78 readme_rst = "" 

79 extra_rst = "" 

80 

81 readme_rst += f"""\ 

82.. image:: {WEBSITE_URL}/logos/banner.png 

83 :alt: Project banner 

84 :align: center 

85 

86| 

87 

88.. |pic_website| image:: {WEBSITE_URL}/badges/website.svg 

89 :alt: Website 

90 :target: {WEBSITE_URL} 

91 

92.. |pic_repository| image:: {WEBSITE_URL}/badges/repository.svg 

93 :alt: Repository 

94 :target: {REPOSITORY_URL} 

95 

96.. |pic_chat| image:: {WEBSITE_URL}/badges/chat.svg 

97 :alt: Chat 

98 :target: {REPOSITORY_URL}/discussions 

99 

100.. |pic_pip_install| image:: {WEBSITE_URL}/badges/pip_install.svg 

101 :alt: pypi 

102 :target: https://pypi.org/project/hdl-registers/ 

103 

104.. |pic_license| image:: {WEBSITE_URL}/badges/license.svg 

105 :alt: License 

106 :target: {WEBSITE_URL}/rst/about/license_information.html 

107 

108.. |pic_ci_status| image:: {REPOSITORY_URL}/actions/workflows/ci.yml/\ 

109badge.svg?branch=main 

110 :alt: CI status 

111 :target: {REPOSITORY_URL}/actions/workflows/ci.yml 

112 

113.. |pic_python_line_coverage| image:: {WEBSITE_URL}/badges/python_coverage.svg 

114 :alt: Python line coverage 

115 :target: {WEBSITE_URL}/python_coverage_html 

116 

117|pic_website| |pic_repository| |pic_pip_install| |pic_license| |pic_chat| |pic_ci_status| 

118|pic_python_line_coverage| 

119 

120The hdl-registers project is an open-source HDL register interface code generator fast enough to run 

121in real time. 

122It makes FPGA/ASIC development more fun by automating a lot of time-consuming manual work. 

123It also minimizes the risk of bugs by removing the need for duplicate information. 

124`Read more <{WEBSITE_URL}/rst/about/about.html>`_ 

125 

126{extra_rst}The following features are supported: 

127 

128* Register fields 

129 

130 * `Bit <{WEBSITE_URL}/rst/field/field_bit.html>`_. 

131 * `Signed/unsigned fixed-point bit vector <{WEBSITE_URL}/rst/field/field_bit_vector.html>`_. 

132 * `Enumeration <{WEBSITE_URL}/rst/field/field_enumeration.html>`_. 

133 * `Positive/negative-range integer <{WEBSITE_URL}/rst/field/field_integer.html>`_. 

134 

135* `Register arrays <{WEBSITE_URL}/rst/basic_feature/basic_feature_register_array.html>`_. 

136* `Default registers <{WEBSITE_URL}/rst/basic_feature/basic_feature_default_registers.html>`_. 

137* `Register constants <{WEBSITE_URL}/rst/constant/constant_overview.html>`_. 

138 

139Registers can be defined using 

140a `TOML/JSON/YAML data file <{WEBSITE_URL}/rst/user_guide/toml_format.html>`_ 

141or the `Python API <{WEBSITE_URL}/rst/user_guide/user_guide_python_api.html>`_. 

142The following code can be generated: 

143 

144* `VHDL <{WEBSITE_URL}/rst/generator/generator_vhdl.html>`_ 

145 

146 * AXI-Lite register file wrapper using records and native VHDL types for values. 

147 * Simulation support packages for compact read/write/wait/checking of register and field values. 

148 

149* `C++ <{WEBSITE_URL}/rst/generator/generator_cpp.html>`_ 

150 

151 * Complete class with setters and getters for registers and fields. 

152 * Includes an abstract interface header for unit test mocking. 

153 

154* `C header <{WEBSITE_URL}/rst/generator/generator_c.html>`_ 

155 with register addresses and field information. 

156 

157* `HTML <{WEBSITE_URL}/rst/generator/generator_html.html>`_ 

158 website with documentation of registers and fields. 

159 

160* `Python <{WEBSITE_URL}/rst/generator/generator_python.html>`_ 

161 class with methods to read/write/print each register and field on a target device. 

162 

163The tool can also be extended by 

164`writing your own code generator <{WEBSITE_URL}/rst/extensions/extensions_custom_generator.html>`_ 

165using a simple but powerful API. 

166 

167This project is mature and used in many production environments. 

168The maintainers place high focus on quality, with everything having good unit test coverage and a 

169thought-out structure. 

170""" 

171 

172 return readme_rst