Coverage for tsfpga/about.py: 32%

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 

10REPOSITORY_URL = "https://github.com/tsfpga/tsfpga" 

11WEBSITE_URL = "https://tsfpga.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 = "A flexible and scalable development platform for modern FPGA projects" 

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 for tsfpga (to be used on website and in PyPI release). 

34 

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

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

37 

38 Arguments: 

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

40 GitHub README. 

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

42 website main page. 

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

44 PyPI release README. 

45 """ 

46 if include_extra_for_github: 

47 readme_rst = "" 

48 extra_rst = f"""\ 

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

50 

51**See PyPI for installation details**: https://pypi.org/project/tsfpga/ 

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 tsfpga 

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

61 

62""" 

63 extra_rst = f"""\ 

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

65To check out the source code go to the `GitHub page <{REPOSITORY_URL}>`__. 

66""" 

67 elif include_extra_for_pypi: 

68 readme_rst = "" 

69 extra_rst = f"""\ 

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

71 

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

73""" 

74 else: 

75 readme_rst = "" 

76 extra_rst = "" 

77 

78 readme_rst += f"""\ 

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

80 :alt: Project banner 

81 :align: center 

82 

83| 

84 

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

86 :alt: Website 

87 :target: {WEBSITE_URL} 

88 

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

90 :alt: Repository 

91 :target: {REPOSITORY_URL} 

92 

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

94 :alt: Chat 

95 :target: {REPOSITORY_URL}/discussions 

96 

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

98 :alt: pypi 

99 :target: https://pypi.org/project/tsfpga/ 

100 

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

102 :alt: License 

103 :target: {WEBSITE_URL}/license_information.html 

104 

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

106badge.svg?branch=main 

107 :alt: CI status 

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

109 

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

111 :alt: Python line coverage 

112 :target: {WEBSITE_URL}/python_coverage_html 

113 

114|pic_website| |pic_repository| |pic_pip_install| |pic_license| |pic_chat| |pic_ci_status| 

115|pic_python_line_coverage| 

116 

117tsfpga is a flexible and scalable development platform for modern FPGA projects. 

118With its Python-based build/simulation flow it is perfect for CI/CD and test-driven development. 

119The API is simple and easy to use 

120(a complete `simulation project <{WEBSITE_URL}/simulation.html>`__ is set up in less than 

12115 lines). 

122 

123{extra_rst} 

124Key features 

125------------ 

126 

127* Source code-centric `project structure <{WEBSITE_URL}/module_structure.html>`__ 

128 for scalability. 

129 Build projects, test configurations, constraints, IP cores, etc. are handled close to the 

130 source code, not in a central monolithic script. 

131* Automatically adds build/simulation sources if a recognized folder structure is used. 

132* Enables `local VUnit test configuration 

133 <{WEBSITE_URL}/simulation.html#local-configuration-of-test-cases>`__ without 

134 multiple ``run.py``. 

135* Handling of `IP cores <{WEBSITE_URL}/simulation.html#simulating-with-vivado-ip-cores>`__ 

136 and `simlib <{WEBSITE_URL}/simulation.html#vivado-simulation-libraries>`__ 

137 for your simulation project, with automatic re-compile when needed. 

138* Python-based `Vivado build system <{WEBSITE_URL}/fpga_build.html>`__ where many builds can 

139 be run in parallel. 

140* Tightly integrated with `hdl-registers <https://hdl-registers.com>`__. 

141 Register code generation is performed before each simulation and each build. 

142* Released under the very permissive BSD 3-Clause License. 

143 

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

145thought-out structure. 

146The project is mature and used in many production environments. 

147""" 

148 

149 return readme_rst