Coverage for tsfpga/about.py: 28%

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 return "A flexible and scalable development platform for modern FPGA projects" 

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

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, GitHub, PyPI). 

36 

37 Arguments: 

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

39 GitHub 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_github: 

46 readme_rst = "" 

47 extra_rst = f"""\ 

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

49 

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

51""" 

52 elif include_extra_for_website: 

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

54 # the correct title. 

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

56 # more clunky. 

57 readme_rst = """\ 

58About tsfpga 

59============ 

60 

61""" 

62 extra_rst = f"""\ 

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

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

65""" 

66 elif include_extra_for_pypi: 

67 readme_rst = "" 

68 extra_rst = f"""\ 

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

70 

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

72""" 

73 else: 

74 readme_rst = "" 

75 extra_rst = "" 

76 

77 readme_rst += f"""\ 

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

79 :alt: Project banner 

80 :align: center 

81 

82| 

83 

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

85 :alt: Website 

86 :target: {WEBSITE_URL} 

87 

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

89 :alt: Repository 

90 :target: {REPOSITORY_URL} 

91 

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

93 :alt: Chat 

94 :target: {REPOSITORY_URL}/discussions 

95 

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

97 :alt: pypi 

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

99 

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

101 :alt: License 

102 :target: {WEBSITE_URL}/license_information.html 

103 

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

105badge.svg?branch=main 

106 :alt: CI status 

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

108 

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

110 :alt: Python line coverage 

111 :target: {WEBSITE_URL}/python_coverage_html 

112 

113|pic_website| |pic_repository| |pic_pip_install| |pic_license| |pic_chat| |pic_ci_status| 

114|pic_python_line_coverage| 

115 

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

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

118The API is simple and easy to use 

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

12015 lines). 

121 

122{extra_rst} 

123Key features 

124------------ 

125 

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

127 for scalability. 

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

129 source code, not in a central monolithic script. 

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

131* Enables `local VUnit test configuration 

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

133 multiple ``run.py``. 

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

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

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

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

138 be run in parallel. 

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

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

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

142 

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

144thought-out structure. 

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

146""" 

147 

148 return readme_rst