Coverage for hdl_registers/about.py: 32%
19 statements
« prev ^ index » next coverage.py v7.6.8, created at 2024-12-01 20:50 +0000
« prev ^ index » next coverage.py v7.6.8, created at 2024-12-01 20:50 +0000
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# --------------------------------------------------------------------------------------------------
10REPOSITORY_URL = "https://github.com/hdl-registers/hdl-registers"
11WEBSITE_URL = "https://hdl-registers.com"
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.
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 = "An open-source HDL register interface code generator fast enough to run in real time"
24 return result
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 (to be used on website and in PyPI release).
34 RST file inclusion in README.rst does not work on GitHub unfortunately, hence this
35 cumbersome handling where the README is duplicated in two places.
37 The arguments control some extra text that is included. This is mainly links to the
38 other places where you can find information on the project (website, GitHub, PyPI).
40 Arguments:
41 include_extra_for_github (bool): Include the extra text that shall be included in the
42 GitHub README.
43 include_extra_for_website (bool): Include the extra text that shall be included in the
44 website main page.
45 include_extra_for_pypi (bool): Include the extra text that shall be included in the
46 PyPI release README.
47 """
48 if include_extra_for_github:
49 readme_rst = ""
50 extra_rst = f"""\
51**See documentation on the website**: {WEBSITE_URL}
53"""
54 elif include_extra_for_website:
55 # The website needs the initial heading, in order for the landing page to get
56 # the correct title.
57 # The others do not need this initial heading, it just makes the GitHub/PyPI page
58 # more clunky.
59 readme_rst = """\
60About hdl-registers
61===================
63"""
64 extra_rst = f"""\
65To install the Python package, see :ref:`installation`.
66To check out the source code go to the
67`GitHub page <{REPOSITORY_URL}>`__. \
68"""
69 elif include_extra_for_pypi:
70 readme_rst = ""
71 extra_rst = f"""\
72**See documentation on the website**: {WEBSITE_URL}
74**Check out the source code on GitHub**: {REPOSITORY_URL}
76"""
77 else:
78 readme_rst = ""
79 extra_rst = ""
81 readme_rst += f"""\
82.. image:: {WEBSITE_URL}/logos/banner.png
83 :alt: Project banner
84 :align: center
86|
88.. |pic_website| image:: {WEBSITE_URL}/badges/website.svg
89 :alt: Website
90 :target: {WEBSITE_URL}
92.. |pic_repository| image:: {WEBSITE_URL}/badges/repository.svg
93 :alt: Repository
94 :target: {REPOSITORY_URL}
96.. |pic_chat| image:: {WEBSITE_URL}/badges/chat.svg
97 :alt: Chat
98 :target: {REPOSITORY_URL}/discussions
100.. |pic_pip_install| image:: {WEBSITE_URL}/badges/pip_install.svg
101 :alt: pypi
102 :target: https://pypi.org/project/hdl-registers/
104.. |pic_license| image:: {WEBSITE_URL}/badges/license.svg
105 :alt: License
106 :target: {WEBSITE_URL}/rst/about/license_information.html
108.. |pic_ci_status| image:: {REPOSITORY_URL}/actions/workflows/ci.yml/\
109badge.svg?branch=main
110 :alt: CI status
111 :target: {REPOSITORY_URL}/actions/workflows/ci.yml
113.. |pic_python_line_coverage| image:: {WEBSITE_URL}/badges/python_coverage.svg
114 :alt: Python line coverage
115 :target: {WEBSITE_URL}/python_coverage_html
117|pic_website| |pic_repository| |pic_pip_install| |pic_license| |pic_chat| |pic_ci_status|
118|pic_python_line_coverage|
120The hdl-registers project is an open-source HDL register interface code generator fast enough to run
121in real time.
122It makes FPGA/ASIC development more fun by automating a lot of time-consuming manual work.
123It also minimizes the risk of bugs by removing the need for duplicate information.
124`Read more <{WEBSITE_URL}/rst/about/about.html>`_
126{extra_rst}The following features are supported:
128* Register fields
130 * `Bit <{WEBSITE_URL}/rst/field/field_bit.html>`_.
131 * `Signed/unsigned fixed-point bit vector <{WEBSITE_URL}/rst/field/field_bit_vector.html>`_.
132 * `Enumeration <{WEBSITE_URL}/rst/field/field_enumeration.html>`_.
133 * `Positive/negative-range integer <{WEBSITE_URL}/rst/field/field_integer.html>`_.
135* `Register arrays <{WEBSITE_URL}/rst/basic_feature/basic_feature_register_array.html>`_.
136* `Default registers <{WEBSITE_URL}/rst/basic_feature/basic_feature_default_registers.html>`_.
137* `Register constants <{WEBSITE_URL}/rst/constant/constant_overview.html>`_.
139Registers can be defined using
140a `TOML/JSON/YAML data file <{WEBSITE_URL}/rst/user_guide/toml_format.html>`_
141or the `Python API <{WEBSITE_URL}/rst/user_guide/user_guide_python_api.html>`_.
142The following code can be generated:
144* `VHDL <{WEBSITE_URL}/rst/generator/generator_vhdl.html>`_
146 * AXI-Lite register file wrapper using records and native VHDL types for values.
147 * Simulation support packages for compact read/write/wait/checking of register and field values.
149* `C++ <{WEBSITE_URL}/rst/generator/generator_cpp.html>`_
151 * Complete class with setters and getters for registers and fields.
152 * Includes an abstract interface header for unit test mocking.
154* `C header <{WEBSITE_URL}/rst/generator/generator_c.html>`_
155 with register addresses and field information.
157* `HTML <{WEBSITE_URL}/rst/generator/generator_html.html>`_
158 website with documentation of registers and fields.
160* `Python <{WEBSITE_URL}/rst/generator/generator_python.html>`_
161 class with methods to read/write/print each register and field on a target device.
163The tool can also be extended by
164`writing your own code generator <{WEBSITE_URL}/rst/extensions/extensions_custom_generator.html>`_
165using a simple but powerful API.
167This project is mature and used in many production environments.
168The maintainers place high focus on quality, with everything having good unit test coverage and a
169thought-out structure.
170"""
172 return readme_rst