Coverage for hdl_registers/about.py: 28%

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 return "An open-source HDL register interface code generator fast enough to run in real time" 

24 

25 

26def get_readme_rst( 

27 include_extra_for_github: bool = False, 

28 include_extra_for_website: bool = False, 

29 include_extra_for_pypi: bool = False, 

30) -> str: 

31 """ 

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

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

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

35 

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

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

38 

39 Arguments: 

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

41 GitHub README. 

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

43 website main page. 

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

45 PyPI release README. 

46 """ 

47 if include_extra_for_github: 

48 readme_rst = "" 

49 extra_rst = f"""\ 

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

51 

52""" 

53 elif include_extra_for_website: 

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

55 # the correct title. 

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

57 # more clunky. 

58 readme_rst = """\ 

59About hdl-registers 

60=================== 

61 

62""" 

63 extra_rst = f"""\ 

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

65To check out the source code go to the 

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

67""" 

68 elif include_extra_for_pypi: 

69 readme_rst = "" 

70 extra_rst = f"""\ 

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

72 

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

74 

75""" 

76 else: 

77 readme_rst = "" 

78 extra_rst = "" 

79 

80 readme_rst += f"""\ 

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

82 :alt: Project banner 

83 :align: center 

84 

85| 

86 

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

88 :alt: Website 

89 :target: {WEBSITE_URL} 

90 

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

92 :alt: Repository 

93 :target: {REPOSITORY_URL} 

94 

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

96 :alt: Chat 

97 :target: {REPOSITORY_URL}/discussions 

98 

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

100 :alt: pypi 

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

102 

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

104 :alt: License 

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

106 

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

108badge.svg?branch=main 

109 :alt: CI status 

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

111 

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

113 :alt: Python line coverage 

114 :target: {WEBSITE_URL}/python_coverage_html 

115 

116|pic_website| |pic_repository| |pic_pip_install| |pic_license| |pic_chat| |pic_ci_status| 

117|pic_python_line_coverage| 

118 

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

120in real time. 

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

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

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

124 

125{extra_rst}The following features are supported: 

126 

127* Register fields 

128 

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

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

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

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

133 

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

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

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

137 

138Registers can be defined using 

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

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

141The following code can be generated: 

142 

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

144 

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

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

147 

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

149 

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

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

152 

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

154 with register addresses and field information. 

155 

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

157 website with documentation of registers and fields. 

158 

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

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

161 

162The tool can also be extended by 

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

164using a simple but powerful API. 

165 

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

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

168thought-out structure. 

169""" 

170 

171 return readme_rst