Coverage for hdl_registers/about.py: 0%

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

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

3# 

4# This file is part of the hdl_registers project, a HDL register generator fast enough to be run 

5# in real time. 

6# https://hdl-registers.com 

7# https://gitlab.com/hdl_registers/hdl_registers 

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

9 

10 

11def get_slogan(): 

12 """ 

13 One-paragraph description of the project. 

14 """ 

15 rst = """\ 

16The hdl_registers project is an open-source HDL register generator fast enough to be run in 

17real time. 

18It can easily be plugged into your development environment so that VHDL register code generation is 

19done before each build and simulation run. 

20For your FPGA release artifacts it can generate headers and documentation.""" 

21 return rst 

22 

23 

24def get_readme_rst( 

25 include_extra_for_gitlab=False, 

26 include_extra_for_website=False, 

27 include_extra_for_pypi=False, 

28): 

29 """ 

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

31 RST file inclusion in README.rst does not work on gitlab unfortunately, hence this 

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

33 

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

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

36 

37 Arguments: 

38 include_extra_for_gitlab (bool): Include the extra text that shall be included in the 

39 gitlab README. 

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

41 website main page. 

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

43 PyPI release README. 

44 """ 

45 if include_extra_for_gitlab: 

46 extra_rst = """\ 

47**See documentation on the website**: https://hdl-registers.com 

48 

49**See PyPI for installation details**: https://pypi.org/project/hdl-registers/ 

50""" 

51 elif include_extra_for_website: 

52 extra_rst = """\ 

53This website contains readable documentation for the project. 

54To check out the source code go to the 

55`gitlab page <https://gitlab.com/hdl_registers/hdl_registers>`__. 

56To install see the `PyPI page <https://pypi.org/project/hdl-registers/>`__. 

57""" 

58 elif include_extra_for_pypi: 

59 extra_rst = """\ 

60**See documentation on the website**: https://hdl-registers.com 

61 

62**Check out the source code on gitlab**: https://gitlab.com/hdl_registers/hdl_registers 

63""" 

64 else: 

65 extra_rst = "" 

66 

67 readme_rst = f"""\ 

68About hdl_registers 

69=================== 

70 

71|pic_website| |pic_gitlab| |pic_gitter| |pic_pip_install| |pic_license| |pic_python_line_coverage| 

72 

73.. |pic_website| image:: https://hdl-registers.com/badges/website.svg 

74 :alt: Website 

75 :target: https://hdl-registers.com 

76 

77.. |pic_gitlab| image:: https://hdl-registers.com/badges/gitlab.svg 

78 :alt: Gitlab 

79 :target: https://gitlab.com/hdl_registers/hdl_registers 

80 

81.. |pic_gitter| image:: https://badges.gitter.im/owner/repo.png 

82 :alt: Gitter 

83 :target: https://gitter.im/tsfpga/tsfpga 

84 

85.. |pic_pip_install| image:: https://hdl-registers.com/badges/pip_install.svg 

86 :alt: pypi 

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

88 

89.. |pic_license| image:: https://hdl-registers.com/badges/license.svg 

90 :alt: License 

91 :target: https://hdl-registers.com/license_information.html 

92 

93.. |pic_python_line_coverage| image:: https://hdl-registers.com/badges/python_coverage.svg 

94 :alt: Python line coverage 

95 :target: https://hdl-registers.com/python_coverage_html 

96 

97{get_slogan()} 

98 

99{extra_rst} 

100The typical use case is to let hdl_registers parse a ``.toml`` file with register definitions that 

101make up a register map. 

102It is also possible to work directly with the Python abstractions as well, without using a 

103data file. 

104The following code can be generated by the tool: 

105 

106* VHDL package containing the register constant values, as well as a type with all the registers 

107 and their modes. 

108 This can be used with a 

109 `generic register file \ 

110<https://hdl-modules.com/modules/reg_file/reg_file.html#axi-lite-reg-file-vhd>`_ 

111 in your VHDL code. 

112* HTML website with documentation of the registers and constants. 

113* C header with constant values, register addresses, and register field information. 

114* C++ header and implementation with constant values, and setters/getters for 

115 registers and fields. 

116 The header has an abstract interface class which can be used for mocking. 

117""" # noqa: E501 

118 

119 return readme_rst