docs: add news fragments for v4.7.0 (#918)

eine · web-flow · commit d181cd36deb8 · 2023-04-20T03:21:18.000+02:00
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -250,15 +250,16 @@ Make sure to use full sentences in the **past or present tense** and use punctua
 Each file should be named like ``<issue #>.<type>.rst``, where ``<issue #>`` is the
 GitHub issue or pull request number, and ``<type>`` is one of:
 
-* ``breaking``: a change which may break existing functionality, such as feature removal
-  or behavior change
-* ``bugfix``: fixes a bug
-* ``change``: backwards compatible features or improvements
-* ``deprecation``: feature deprecation
-* ``misc``: a ticket was closed, but it is not necessarily important for the user
+* ``breaking``:may break existing functionality; such as feature removal or behavior change.
+* ``bugfix``: fixes a bug.
+* ``doc``: related to the documentation.
+* ``deprecation``: feature deprecation.
+* ``feature``: backwards compatible feature addition or improvement.
+* ``misc``: a ticket was closed, but it is not necessarily important for the user.
 
 For example: ``123.feature.rst``, ``456.bugfix.rst``.
 
-``towncrier`` preserves multiple paragraphs and formatting
-(code blocks, lists, and so on), but for entries other than features, it is usually
-better to stick to a single paragraph to keep it concise.
+.. HINT::
+  ``towncrier`` preserves multiple paragraphs and formatting
+  (code blocks, lists, and so on), but for entries other than features, it is usually better to stick
+  to a single paragraph to keep it concise.
diff --git a/docs/installing.rst b/docs/installing.rst
@@ -80,7 +80,7 @@ VHDL or SystemVerilog
 Using the Python Package Manager
 ================================
 
-The recommended way to get VUnit is to install the :ref:`latest stable release <latest_release>` via `pip <https://pip.pypa.io/en/stable/>`__:
+The recommended way to get VUnit is to install the :ref:`latest stable release <release:latest>` via `pip <https://pip.pypa.io/en/stable/>`__:
 
 .. code-block:: console
 
diff --git a/docs/news.d/+2896a1e3.feature.rst b/docs/news.d/+2896a1e3.feature.rst
@@ -0,0 +1 @@
+Introduce new class ``LibraryList`` and add method to get list of libraries from VUnit object.
diff --git a/docs/news.d/+758b9e47.deprecation.rst b/docs/news.d/+758b9e47.deprecation.rst
@@ -0,0 +1 @@
+[JSON-for-VHDL] Bump to ``95e848b8``.
diff --git a/docs/news.d/+84eedd22.misc.rst b/docs/news.d/+84eedd22.misc.rst
@@ -0,0 +1 @@
+Add utilities to create HTML from code snippets and VUnit logs.
diff --git a/docs/news.d/+953d1904.doc.rst b/docs/news.d/+953d1904.doc.rst
@@ -0,0 +1 @@
+Add blog post on VUnit's relation to other frameworks.
diff --git a/docs/news.d/+9775342d.doc.rst b/docs/news.d/+9775342d.doc.rst
@@ -0,0 +1 @@
+Add blog post on FPGA World 2022 in Stockholm.
diff --git a/docs/news.d/+cba27423.deprecation.rst b/docs/news.d/+cba27423.deprecation.rst
@@ -0,0 +1 @@
+Python 3.6 was EOL in Dec 2021; use Python 3.7 as the minimum tested version.
diff --git a/docs/news.d/356.bugfix.rst b/docs/news.d/356.bugfix.rst
@@ -0,0 +1 @@
+[JSON-for-VHDL] Fix invalid XML characters in the example.
diff --git a/docs/news.d/44.feature.rst b/docs/news.d/44.feature.rst
@@ -0,0 +1 @@
+Add NVC simulator support.
diff --git a/docs/news.d/559.deprecation.rst b/docs/news.d/559.deprecation.rst
@@ -0,0 +1,2 @@
+Add ``compile_builtins`` deprecation warning.
+Use ``add_vhdl_builtins`` and/or ``add_verilog_builtins`` instead.
diff --git a/docs/news.d/573.bugfix.rst b/docs/news.d/573.bugfix.rst
@@ -0,0 +1 @@
+Fix AXI Stream slave back to back transfers.
diff --git a/docs/news.d/576.doc.rst b/docs/news.d/576.doc.rst
@@ -0,0 +1 @@
+Add timing diagrams to the Check Library user guide.
diff --git a/docs/news.d/621.bugfix.rst b/docs/news.d/621.bugfix.rst
@@ -0,0 +1 @@
+[Riviera-PRO] Fix for RUNTIME_0232 and RUNTIME_022 messages.
diff --git a/docs/news.d/642.bugfix.rst b/docs/news.d/642.bugfix.rst
@@ -0,0 +1 @@
+Fix delta cycle race conditions.
diff --git a/docs/news.d/754.deprecation.rst b/docs/news.d/754.deprecation.rst
@@ -0,0 +1 @@
+[OSVVM] Bump to 2022.04.
diff --git a/docs/news.d/757.deprecation.rst b/docs/news.d/757.deprecation.rst
@@ -0,0 +1,2 @@
+Add ``compile_builtins`` deprecation warning.
+Use ``add_vhdl_builtins`` and/or ``add_verilog_builtins`` instead.
diff --git a/docs/news.d/757.doc.rst b/docs/news.d/757.doc.rst
@@ -0,0 +1 @@
+Add ``add_vhdl_builtins`` and ``add_verilog_builtins``.
diff --git a/docs/news.d/767.feature.rst b/docs/news.d/767.feature.rst
@@ -0,0 +1 @@
+Skip addition of built-in dependencies (OSVVM and/or JSON-for-VHDL) if the library is added previously.
diff --git a/docs/news.d/768.bugfix.rst b/docs/news.d/768.bugfix.rst
@@ -0,0 +1 @@
+Skip non-generic OSVVM packages when the simulator supports generics.
diff --git a/docs/news.d/769.bugfix.rst b/docs/news.d/769.bugfix.rst
@@ -0,0 +1 @@
+Skip non-generic OSVVM packages when the simulator supports generics.
diff --git a/docs/news.d/771.feature.rst b/docs/news.d/771.feature.rst
@@ -0,0 +1 @@
+Skip addition of built-in dependencies (OSVVM and/or JSON-for-VHDL) if the library is added previously.
diff --git a/docs/news.d/773.bugfix.rst b/docs/news.d/773.bugfix.rst
@@ -0,0 +1 @@
+Fix location preprocessor casing bug.
diff --git a/docs/news.d/774.bugfix.rst b/docs/news.d/774.bugfix.rst
@@ -0,0 +1 @@
+Fix location preprocessor casing bug.
diff --git a/docs/news.d/777.deprecation.rst b/docs/news.d/777.deprecation.rst
@@ -0,0 +1,2 @@
+Add ``compile_builtins`` deprecation warning.
+Use ``add_vhdl_builtins`` and/or ``add_verilog_builtins`` instead.
diff --git a/docs/news.d/778.deprecation.rst b/docs/news.d/778.deprecation.rst
@@ -0,0 +1,2 @@
+Add ``compile_builtins`` deprecation warning.
+Use ``add_vhdl_builtins`` and/or ``add_verilog_builtins`` instead.
diff --git a/docs/news.d/779.doc.rst b/docs/news.d/779.doc.rst
@@ -0,0 +1 @@
+Add section Overview, including a diagram.
diff --git a/docs/news.d/780.deprecation.rst b/docs/news.d/780.deprecation.rst
@@ -0,0 +1 @@
+[OSVVM] Bump to 2022.04.
diff --git a/docs/news.d/781.bugfix.rst b/docs/news.d/781.bugfix.rst
@@ -0,0 +1 @@
+Support detecting and failing on ambiguous direct entity instantiations.
diff --git a/docs/news.d/782.bugfix.rst b/docs/news.d/782.bugfix.rst
@@ -0,0 +1 @@
+[Vivado] Add flag ``fail_on_non_hdl_files``.
diff --git a/docs/news.d/786.bugfix.rst b/docs/news.d/786.bugfix.rst
@@ -0,0 +1 @@
+[Vivado] Add flag ``fail_on_non_hdl_files``.
diff --git a/docs/news.d/790.deprecation.rst b/docs/news.d/790.deprecation.rst
@@ -0,0 +1 @@
+[OSVVM] Bump to 2022.04.
diff --git a/docs/news.d/792.bugfix.rst b/docs/news.d/792.bugfix.rst
@@ -0,0 +1 @@
+Fix parsing of port type starting with signal.
diff --git a/docs/news.d/794.bugfix.rst b/docs/news.d/794.bugfix.rst
@@ -0,0 +1 @@
+Fix false pass.
diff --git a/docs/news.d/797.bugfix.rst b/docs/news.d/797.bugfix.rst
@@ -0,0 +1 @@
+Fix axi_lite_master wait behaviour if idle.
diff --git a/docs/news.d/801.doc.rst b/docs/news.d/801.doc.rst
@@ -0,0 +1 @@
+Improve documentation for ``pre_config`` and ``post_check``.
diff --git a/docs/news.d/810.doc.rst b/docs/news.d/810.doc.rst
@@ -0,0 +1 @@
+Improve help of CLI option ``--clean``.
diff --git a/docs/news.d/813.bugfix.rst b/docs/news.d/813.bugfix.rst
@@ -0,0 +1 @@
+Fix delta cycle race conditions.
diff --git a/docs/news.d/815.feature.rst b/docs/news.d/815.feature.rst
@@ -0,0 +1 @@
+Add method to get list of libraries from VUnit object.
diff --git a/docs/news.d/816.doc.rst b/docs/news.d/816.doc.rst
@@ -0,0 +1 @@
+ Added LibraryList.
diff --git a/docs/news.d/819.bugfix.rst b/docs/news.d/819.bugfix.rst
@@ -0,0 +1 @@
+Handle PermissionError while listing available simulators.
diff --git a/docs/news.d/820.bugfix.rst b/docs/news.d/820.bugfix.rst
@@ -0,0 +1 @@
+Handle PermissionError while listing available simulators.
diff --git a/docs/news.d/821.doc.rst b/docs/news.d/821.doc.rst
@@ -0,0 +1 @@
+Fix typos.
diff --git a/docs/news.d/823.doc.rst b/docs/news.d/823.doc.rst
@@ -0,0 +1 @@
+Add timing diagrams to the Check Library user guide.
diff --git a/docs/news.d/825.bugfix.rst b/docs/news.d/825.bugfix.rst
@@ -0,0 +1 @@
+[Riviera-PRO] Fix for RUNTIME_0232 and RUNTIME_022 messages.
diff --git a/docs/news.d/826.bugfix.rst b/docs/news.d/826.bugfix.rst
@@ -0,0 +1 @@
+Fix parsing of port type starting with signal.
diff --git a/docs/news.d/827.deprecation.rst b/docs/news.d/827.deprecation.rst
@@ -0,0 +1 @@
+[OSVVM] Bump to 2022.04.
diff --git a/docs/news.d/830.feature.rst b/docs/news.d/830.feature.rst
@@ -0,0 +1 @@
+Make ``dict_t`` type generic.
diff --git a/docs/news.d/832.doc.rst b/docs/news.d/832.doc.rst
@@ -0,0 +1 @@
+Fix typos.
diff --git a/docs/news.d/834.doc.rst b/docs/news.d/834.doc.rst
@@ -0,0 +1 @@
+Clarify that ``VUNIT_SIMULATOR`` is set to ``modelsim`` when using Questa.
diff --git a/docs/news.d/835.feature.rst b/docs/news.d/835.feature.rst
@@ -0,0 +1 @@
+Make ``dict_t`` type generic.
diff --git a/docs/news.d/838.bugfix.rst b/docs/news.d/838.bugfix.rst
@@ -0,0 +1 @@
+[ModelSim/Questa] Workaround for compilation bug.
diff --git a/docs/news.d/840.bugfix.rst b/docs/news.d/840.bugfix.rst
@@ -0,0 +1 @@
+[ModelSim/Questa] Workaround for compilation bug.
diff --git a/docs/news.d/845.bugfix.rst b/docs/news.d/845.bugfix.rst
@@ -0,0 +1 @@
+[JSON-for-VHDL] Fix invalid XML characters in the example.
diff --git a/docs/news.d/849.doc.rst b/docs/news.d/849.doc.rst
@@ -0,0 +1 @@
+Improve documentation for ``pre_config`` and ``post_check``.
diff --git a/docs/news.d/850.doc.rst b/docs/news.d/850.doc.rst
@@ -0,0 +1 @@
+Clarify that ``VUNIT_SIMULATOR`` is set to ``modelsim`` when using Questa.
diff --git a/docs/news.d/852.bugfix.rst b/docs/news.d/852.bugfix.rst
@@ -0,0 +1 @@
+Support generics with explicit constant declaration.
diff --git a/docs/news.d/854.bugfix.rst b/docs/news.d/854.bugfix.rst
@@ -0,0 +1 @@
+Support generics with explicit constant declaration.
diff --git a/docs/news.d/855.doc.rst b/docs/news.d/855.doc.rst
@@ -0,0 +1 @@
+Improve help of CLI option ``--clean``.
diff --git a/docs/news.d/856.bugfix.rst b/docs/news.d/856.bugfix.rst
@@ -0,0 +1 @@
+Fix axi_lite_master wait behaviour if idle.
diff --git a/docs/news.d/858.bugfix.rst b/docs/news.d/858.bugfix.rst
@@ -0,0 +1 @@
+Fix AXI Stream slave back to back transfers.
diff --git a/docs/news.d/868.misc.rst b/docs/news.d/868.misc.rst
@@ -0,0 +1 @@
+Replace ``inspect.getargspec`` method, removed in Python 3.11.
diff --git a/docs/news.d/870.misc.rst b/docs/news.d/870.misc.rst
@@ -0,0 +1 @@
+Test support on Python 3.11.
diff --git a/docs/news.d/872.feature.rst b/docs/news.d/872.feature.rst
@@ -0,0 +1 @@
+Add support for byte enable to Avalon slave.
diff --git a/docs/news.d/874.doc.rst b/docs/news.d/874.doc.rst
@@ -0,0 +1 @@
+Improve documentation of ``check_enabled``.
diff --git a/docs/news.d/875.feature.rst b/docs/news.d/875.feature.rst
@@ -0,0 +1 @@
+[Active-HDL] Enable VHDL-2019.
diff --git a/docs/news.d/887.doc.rst b/docs/news.d/887.doc.rst
@@ -0,0 +1 @@
+Added Identity package user guide.
diff --git a/docs/news.d/887.feature.rst b/docs/news.d/887.feature.rst
@@ -0,0 +1 @@
+Add Identity package.
diff --git a/docs/news.d/888.doc.rst b/docs/news.d/888.doc.rst
@@ -0,0 +1 @@
+Added Identity package user guide.
diff --git a/docs/news.d/898.bugfix.rst b/docs/news.d/898.bugfix.rst
@@ -0,0 +1 @@
+Detect GHDL backend with newer GCC|LLVM.
diff --git a/docs/news.d/901.bugfix.rst b/docs/news.d/901.bugfix.rst
@@ -0,0 +1 @@
+Detect GHDL backend with newer GCC|LLVM.
diff --git a/docs/news.d/903.feature.rst b/docs/news.d/903.feature.rst
@@ -0,0 +1 @@
+[VHDL-2019] Support interface lists with trailing comma.
diff --git a/docs/news.d/904.feature.rst b/docs/news.d/904.feature.rst
@@ -0,0 +1 @@
+Add NVC simulator support.
diff --git a/docs/news.d/908.feature.rst b/docs/news.d/908.feature.rst
@@ -0,0 +1 @@
+[VHDL-2019] Add method ``supports_vhdl_call_paths`` to the simulator interface.
diff --git a/docs/news.d/911.misc.rst b/docs/news.d/911.misc.rst
@@ -0,0 +1 @@
+[CI] Add workflow_dispatch.
diff --git a/docs/news.d/917.misc.rst b/docs/news.d/917.misc.rst
@@ -0,0 +1 @@
+[CI] Add NVC jobs.
diff --git a/pyproject.toml b/pyproject.toml
@@ -32,13 +32,18 @@ underlines = ["-", "~"]
     showcontent = true
 
     [[tool.towncrier.type]]
-    directory = "change"
-    name = "Changes"
+    directory = "deprecation"
+    name = "Deprecations"
     showcontent = true
 
     [[tool.towncrier.type]]
-    directory = "deprecation"
-    name = "Deprecations"
+    directory = "doc"
+    name = "Documentation"
+    showcontent = true
+
+    [[tool.towncrier.type]]
+    directory = "feature"
+    name = "Features"
     showcontent = true
 
     [[tool.towncrier.type]]
diff --git a/tools/create_release_notes.py b/tools/create_release_notes.py
@@ -9,66 +9,55 @@
 """
 
 from pathlib import Path
-from os.path import relpath
-from glob import glob
 from subprocess import check_call, check_output, CalledProcessError
 from shutil import which
-import datetime
-
-
-def get_releases(source_path: Path):
-    """
-    Get all releases defined by release note files
-    """
-    release_notes = source_path / "release_notes"
-    releases = []
-    for idx, file_name in enumerate(sorted(glob(str(release_notes / "*.rst")), reverse=True)):
-        releases.append(Release(file_name, is_latest=idx == 0))
-    return releases
+from datetime import datetime
 
 
 def create_release_notes():
     """
     Create monolithic release notes file from several input files
     """
-    source_path = Path(__file__).parent.parent / "docs"
-
-    check_call(["towncrier", "build", "--keep"], cwd=source_path.parent)
-
-    releases = get_releases(source_path)
-    latest_release = releases[0]
-
-    with (source_path / "release_notes.inc").open("w", encoding="utf-8") as fptr:
-        fptr.write(
-            "`Commits since last release "
-            f"<https://github.com/VUnit/vunit/compare/{latest_release.tag!s}...master>`__"
+    root = Path(__file__).parent.parent
+    docsroot = root / "docs"
+
+    check_call(["towncrier", "build", "--keep"], cwd=root)
+
+    # Get all releases defined by release note files
+    releases = [
+        Release(file_name, is_latest=idx == 0)
+        for idx, file_name in enumerate(sorted((docsroot / "release_notes").glob("*.rst"), reverse=True))
+    ]
+
+    content = (
+        "`Commits since last release "
+        f"<https://github.com/VUnit/vunit/compare/v{releases[0].name!s}...master>`__"
+        "\n\n"
+    )
+
+    for idx, release in enumerate(releases):
+        title = f":vunit_commit:`{release.name!s} <v{release.name!s}>` - {release.date.strftime('%Y-%m-%d')}"
+
+        if idx == 0:
+            title += " (latest)"
+            content += ".. _release:latest:\n\n"
+
+        content += (
+            f".. _release:{release.name}:\n\n"
+            f"{title}\n{'-' * len(title)}\n\n"
+            f"`Download from PyPI <https://pypi.python.org/pypi/vunit_hdl/{release.name!s}/>`__"
         )
 
-        fptr.write("\n\n")
-
-        for idx, release in enumerate(releases):
-            is_last = idx == len(releases) - 1
-
-            if release.is_latest:
-                fptr.write(".. _latest_release:\n\n")
-
-            title = f":vunit_commit:`{release.name!s} <{release.tag!s}>` - {release.date.strftime('%Y-%m-%d')!s}"
-            if release.is_latest:
-                title += " (latest)"
-            fptr.write(title + "\n")
-            fptr.write("-" * len(title) + "\n\n")
+        if idx != len(releases) - 1:
+            content += (
+                f" | `Commits since previous release "
+                f"<https://github.com/VUnit/vunit/compare/v{releases[idx + 1].name!s}...v{release.name!s}>`__"
+            )
 
-            fptr.write(f"\n`Download from PyPI <https://pypi.python.org/pypi/vunit_hdl/{release.name!s}/>`__")
+        content += f"\n\n.. include:: release_notes/{release.name}{release.suffix}\n\n\n"
 
-            if not is_last:
-                fptr.write(
-                    f" | `Commits since previous release "
-                    f"<https://github.com/VUnit/vunit/compare/{releases[idx + 1].tag!s}...{release.tag!s}>`__"
-                )
-
-            fptr.write("\n\n")
-
-            fptr.write(f".. include:: {relpath(release.file_name, source_path)!s}\n")
+    with open(str(docsroot / "release_notes.inc"), "w", encoding="utf-8") as fptr:
+        fptr.write(content)
 
 
 class Release(object):
@@ -77,33 +66,27 @@ class Release(object):
     """
 
     def __init__(self, file_name, is_latest):
-        self.file_name = file_name
-        self.name = str(Path(file_name).with_suffix("").name)
-        self.tag = "v" + self.name
-        self.is_latest = is_latest
+        self.suffix = file_name.suffix
+        self.name = file_name.stem
+        tag = "v" + self.name
 
-        try:
-            self.date = _get_date(self.tag)
+        git = which("git")
+        if git is None:
+            raise BaseException("'git' is required!")
 
+        try:
+            self._get_date(git, tag)
         except CalledProcessError:
-            if self.is_latest:
-                # Release tag for latest release not yet created, assume HEAD will become release
-                print(f"Release tag {self.tag!s} not created yet, use HEAD for date")
-                self.date = _get_date("HEAD")
-            else:
+            if not is_latest:
                 raise
-
-        with Path(file_name).open("r", encoding="utf-8") as fptr:
-            self.notes = fptr.read()
-
-
-def _get_date(commit):
-    """
-    Get date
-    """
-    git = which("git")
-    if git is None:
-        raise BaseException("'git' is required!")
-    date_str = check_output([git, "log", "-1", "--format=%ci", commit]).decode().strip()
-    date_str = " ".join(date_str.split(" ")[0:2])
-    return datetime.datetime.strptime(date_str, "%Y-%m-%d %H:%M:%S")
+            print(f"Release tag {tag} not created yet, use HEAD for date")
+            self._get_date(git, "HEAD")
+
+    def _get_date(self, git, ref):
+        """
+        Get date
+        """
+        self.date = datetime.strptime(
+            " ".join(check_output([git, "log", "-1", "--format=%ci", ref]).decode().strip().split(" ")[0:2]),
+            "%Y-%m-%d %H:%M:%S",
+        )
