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/tsfpga/hdl_registers 

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

9 

10 

11def get_slogan(): 

12 rst = """\ 

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

14real time. 

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

16done before each build and simulation run. 

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

18 return rst 

19 

20 

21def get_readme_rst( 

22 include_extra_for_gitlab=False, 

23 include_extra_for_website=False, 

24 include_extra_for_pypi=False, 

25): 

26 """ 

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

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

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

30 

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

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

33 

34 Arguments: 

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

36 gitlab README. 

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

38 website main page. 

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

40 PyPI release README. 

41 """ 

42 if include_extra_for_gitlab: 

43 extra_rst = """\ 

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

45 

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

47""" 

48 elif include_extra_for_website: 

49 extra_rst = """\ 

50This website contains readable documentation for the project. 

51To check out the source code go to the `gitlab page <https://gitlab.com/tsfpga/hdl_registers>`__. 

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

53""" 

54 elif include_extra_for_pypi: 

55 extra_rst = """\ 

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

57 

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

59""" 

60 else: 

61 extra_rst = "" 

62 

63 readme_rst = f"""\ 

64About hdl_registers 

65=================== 

66 

67|pic_website| |pic_gitlab| |pic_gitter| |pic_pip_install| |pic_license| |pic_python_line_coverage| 

68 

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

70 :alt: Website 

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

72 

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

74 :alt: Gitlab 

75 :target: https://gitlab.com/tsfpga/hdl_registers 

76 

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

78 :alt: Gitter 

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

80 

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

82 :alt: pypi 

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

84 

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

86 :alt: License 

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

88 

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

90 :alt: Python line coverage 

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

92 

93{get_slogan()} 

94 

95{extra_rst} 

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

97make up a register map. 

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

99data file. 

100From the Python abstractions, the following code can be generated: 

101 

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

103 and their modes. 

104 This can then be used with a 

105 `generic register file \ 

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

107 in the VHDL code. 

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

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

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

111 registers and fields. 

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

113""" # noqa: E501 

114 

115 return readme_rst