.gitlab-ci.yml

 # Instructions here: https://docs.gitlab.com/ee/ci/yaml/
 # Linter here: https://gitlab.com/tsfpga/hdl_modules/-/ci/lint
+# We mainly use a docker images that are built for tsfpga CI.
+# See the "docker" folder in the tsfpga repo for details.
 
 stages:
   - test
@@ -21,11 +23,6 @@ workflow:
 default:
   # A running job should be canceled if made redundant by a newer pipeline run.
   interruptible: true
-  # Use docker image from ghdl project
-  # Available at https://hub.docker.com/r/ghdl/vunit/
-  # Configured at https://github.com/ghdl/docker/
-  # Note that the mcode image is much smaller than the gcc image.
-  image: ghdl/vunit:mcode-master
   before_script:
     - echo $CI_COMMIT_TAG
     - echo $CI_COMMIT_BRANCH
@@ -36,27 +33,24 @@ default:
 
 pytest:
   stage: test
+  image: tsfpga/ci_py_sim
   script:
-    - apt-get update -qq > /dev/null
-    - apt-get install -y -qq git > /dev/null
     - git clone --depth 1 --single-branch --branch master https://gitlab.com/tsfpga/tsfpga.git ../tsfpga
-    - python3 -m pip install black flake8 pylint pytest GitPython > /dev/null
     - python3 -m pytest -v test
 
 
 simulate:
   stage: test
+  image: tsfpga/ci_py_sim
   script:
-    - apt-get update -qq > /dev/null
-    - apt-get install -y -qq git > /dev/null
-    - git clone --depth 1 --single-branch --branch master https://gitlab.com/tsfpga/tsfpga.git ../tsfpga
-    - python3 -m pip install tomlkit GitPython > /dev/null
-    # We seem to need this for some reason. Without it, the "simulate.py --vcs-minimal" call can not
+    # We seem to need "git fetch" for some reason.
+    # Without it, the "simulate.py --vcs-minimal" call can not
     # resolve "origin/master" (and running "git branch -a" comes out empty). The tsfpga repo, which
     # has pretty much identical settings, does not have this issue.
     # Might have something to do with a shallow clone strategy, or a gitlab bug related to the
     # project being private and then made public. For now this workaround works, so it is fine.
     - git fetch
+    - git clone --depth 1 --single-branch --branch master https://gitlab.com/tsfpga/tsfpga.git ../tsfpga
     # Run minimal simulation subset for merge requests
     - if [ $CI_PIPELINE_SOURCE == "merge_request_event" ]; then export SIMULATE_FLAGS="--vcs-minimal"; fi;
     - python3 tools/simulate.py --num-threads 4 --vivado-skip $SIMULATE_FLAGS
@@ -64,11 +58,9 @@ simulate:
 
 build_pages:
   stage: test
+  image: tsfpga/ci_py_sim_sphinx
   script:
-    - apt-get update -qq > /dev/null
-    - apt-get install -y -qq git graphviz > /dev/null
     - git clone --depth 1 --single-branch --branch master https://gitlab.com/tsfpga/tsfpga.git ../tsfpga
-    - python3 -m pip install GitPython pybadges sphinx sphinx-rtd-theme sphinx_sitemap > /dev/null
     - python3 tools/build_docs.py
   artifacts:
     paths:

doc/release_notes/1.0.0.rst

+Use ``get_hdl_modules()`` call in all ``module_*.py``.

doc/sphinx/conf.py

@@ -6,35 +6,23 @@
 # https://gitlab.com/tsfpga/hdl_modules
 # --------------------------------------------------------------------------------------------------
 
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
+"""
+Configuration file for the Sphinx documentation builder.
+"""
 
 project = "hdl_modules"
 copyright = "Lukas Vik"
 author = "Lukas Vik"
 
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
-# ones.
 extensions = [
     "sphinx.ext.graphviz",
     "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
     "sphinx_sitemap",
+    "symbolator_sphinx",
 ]
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+symbolator_output_format = "png"
 
 # Base URL for generated sitemap XML
 html_baseurl = "https://hdl-modules.com"
@@ -42,9 +30,6 @@ html_baseurl = "https://hdl-modules.com"
 # Include robots.txt which points to sitemap
 html_extra_path = ["robots.txt"]
 
-
-# -- Options for HTML output -------------------------------------------------
-
 html_theme = "sphinx_rtd_theme"
 
 html_theme_options = {

doc/sphinx/index.rst

@@ -7,3 +7,16 @@
     license_information
     contributing
     release_notes
+
+
+.. toctree::
+    :caption: HDL modules
+    :hidden:
+
+    modules/axi
+    modules/bfm
+    modules/common
+    modules/fifo
+    modules/math
+    modules/reg_file
+    modules/resync

doc/sphinx/modules/axi.rst

+.. include:: ../../../generated/sphinx/modules/axi.rst

doc/sphinx/modules/bfm.rst

+.. include:: ../../../generated/sphinx/modules/bfm.rst

doc/sphinx/modules/common.rst

+.. include:: ../../../generated/sphinx/modules/common.rst

doc/sphinx/modules/fifo.rst

+.. include:: ../../../generated/sphinx/modules/fifo.rst

doc/sphinx/modules/math.rst

+.. include:: ../../../generated/sphinx/modules/math.rst

doc/sphinx/modules/reg_file.rst

+.. include:: ../../../generated/sphinx/modules/reg_file.rst

doc/sphinx/modules/resync.rst

+.. include:: ../../../generated/sphinx/modules/resync.rst

modules/axi/module_axi.py

@@ -6,7 +6,7 @@
 # https://gitlab.com/tsfpga/tsfpga
 # --------------------------------------------------------------------------------------------------
 
-from tsfpga.module import BaseModule, get_tsfpga_modules
+from tsfpga.module import BaseModule, get_hdl_modules
 from tsfpga.vivado.project import VivadoNetlistProject
 
 
@@ -75,7 +75,7 @@ class Module(BaseModule):
 
     def get_build_projects(self):
         projects = []
-        modules = get_tsfpga_modules(names_include=[self.name, "common", "math"])
+        modules = get_hdl_modules(names_include=[self.name, "common", "math"])
         part = "xc7z020clg400-1"
 
         generics = dict(

modules/common/module_common.py

@@ -8,7 +8,7 @@
 
 import itertools
 
-from tsfpga.module import BaseModule, get_tsfpga_modules
+from tsfpga.module import BaseModule, get_hdl_modules
 from tsfpga.vivado.project import VivadoNetlistProject
 from tsfpga.vivado.build_result_checker import (
     EqualTo,
@@ -274,7 +274,7 @@ class Module(BaseModule):
             )
 
     def _get_clock_counter_build_projects(self, part, projects):
-        modules = get_tsfpga_modules(names_include=[self.name, "math", "resync"])
+        modules = get_hdl_modules(names_include=[self.name, "math", "resync"])
 
         generics = dict(resolution_bits=24, max_relation_bits=6)
         projects.append(
@@ -309,7 +309,7 @@ class Module(BaseModule):
         )
 
     def _get_period_pulser_build_projects(self, part, projects):
-        modules = get_tsfpga_modules(names_include=[self.name, "math"])
+        modules = get_hdl_modules(names_include=[self.name, "math"])
 
         periods = [32, 37, 300, 63 * 64, 311000000]
         total_luts = [2, 7, 4, 5, 18]

modules/common/src/periodic_pulser.vhd

@@ -16,25 +16,30 @@
 -- on each count enable, a fixed period is created.
 -- The remaining period is sent to a new instance of period_pulser.
 --
--- Step 1:
+-- **Step 1**:
 -- As far as possible and-gate multiple shift registers together. The output of this stage
 -- is then sent to the next instance of period_pulser
 -- This method only works if the lengths are mutual primes.
 -- One or more shift registers may be created.
 --
--- Step 2:
+-- **Step 2**:
 -- If the factor cannot be further broken down, add a simple counter.
 --
--- -------------------------------------------------------------------------------------------------
--- Example:
+-- Example
+-- _______
+--
 -- Let's say that the maximum shift register length is 16.
 -- A period of 12*37 can then be achieved using two shift registers of length 4 and 3,
--- and then instantiating a new period_pulser:
--- [0][0][0][1]
---             \
---               [and] -> pulse -> [period_pulser of period 37]
---             /
+-- and then instantiating a new period_pulser
+--
+-- .. code-block:: none
+--
+--    [0][0][0][1]
+--                \
+--                  [and] -> pulse -> [period_pulser of period 37]
+--                /
+--       [0][0][1]
+--
 -- The next stage will create a counter, because 37 is a prime larger than the maximum shift
 -- register length.
 -- -------------------------------------------------------------------------------------------------

modules/fifo/module_fifo.py

@@ -6,7 +6,7 @@
 # https://gitlab.com/tsfpga/tsfpga
 # --------------------------------------------------------------------------------------------------
 
-from tsfpga.module import BaseModule, get_tsfpga_modules
+from tsfpga.module import BaseModule, get_hdl_modules
 from tsfpga.vivado.project import VivadoNetlistProject
 from tsfpga.vivado.build_result_checker import (
     EqualTo,
@@ -116,7 +116,7 @@ class Module(BaseModule):
 
     def get_build_projects(self):
         projects = []
-        modules = get_tsfpga_modules()
+        modules = get_hdl_modules()
         part = "xc7z020clg400-1"
 
         self._setup_fifo_build_projects(projects, modules, part)

modules/reg_file/module_reg_file.py

@@ -6,7 +6,7 @@
 # https://gitlab.com/tsfpga/tsfpga
 # --------------------------------------------------------------------------------------------------
 
-from tsfpga.module import BaseModule, get_tsfpga_modules
+from tsfpga.module import BaseModule, get_hdl_modules
 from tsfpga.vivado.project import VivadoNetlistProject
 from tsfpga.vivado.build_result_checker import (
     EqualTo,
@@ -37,7 +37,7 @@ class Module(BaseModule):
 
     def get_build_projects(self):  # pylint: disable=no-self-use
         projects = []
-        all_modules = get_tsfpga_modules()
+        all_modules = get_hdl_modules()
         part = "xc7z020clg400-1"
 
         projects.append(

modules/resync/module_resync.py

@@ -6,7 +6,7 @@
 # https://gitlab.com/tsfpga/tsfpga
 # --------------------------------------------------------------------------------------------------
 
-from tsfpga.module import BaseModule, get_tsfpga_modules
+from tsfpga.module import BaseModule, get_hdl_modules
 from tsfpga.vivado.build_result_checker import EqualTo, Ffs, TotalLuts
 from tsfpga.vivado.project import VivadoNetlistProject
 
@@ -61,7 +61,7 @@ class Module(BaseModule):
 
     def get_build_projects(self):
         projects = []
-        modules = get_tsfpga_modules()
+        modules = get_hdl_modules()
         part = "xc7z020clg400-1"
         generics = dict(width=16)
 

tools/build_docs.py

@@ -10,6 +10,8 @@ from pybadges import badge
 
 import hdl_modules_tools_env
 
+from tsfpga.module import get_modules
+from tsfpga.module_documentation import ModuleDocumentation
 from tsfpga.system_utils import create_directory, create_file, delete, read_file
 from tsfpga.tools.sphinx_doc import build_sphinx, generate_release_notes
 
@@ -29,12 +31,22 @@ def main():
     )
     create_file(GENERATED_SPHINX / "release_notes.rst", rst)
 
+    generate_module_documentation()
+
     generate_sphinx_index()
 
     build_sphinx(build_path=SPHINX_DOC, output_path=GENERATED_SPHINX_HTML)
 
-    badges_path = create_directory(GENERATED_SPHINX_HTML / "badges")
-    build_information_badges(badges_path)
+    build_information_badges()
+
+
+def generate_module_documentation():
+    modules = get_modules(modules_folders=[hdl_modules_tools_env.HDL_MODULES_DIRECTORY])
+    for module in modules:
+        module_documentation = ModuleDocumentation(module)
+        rst = module_documentation.get_rst_document()
+
+        create_file(GENERATED_SPHINX / "modules" / f"{module.name}.rst", rst)
 
 
 def get_readme_rst():
@@ -106,7 +118,9 @@ def generate_sphinx_index():
     create_file(GENERATED_SPHINX / "index.rst", rst)
 
 
-def build_information_badges(output_path):
+def build_information_badges():
+    output_path = create_directory(GENERATED_SPHINX_HTML / "badges")
+
     badge_svg = badge(left_text="license", right_text="BSD 3-Clause", right_color="blue")
     create_file(output_path / "license.svg", badge_svg)
 

tools/tag_release.py

@@ -47,11 +47,13 @@ def verify_new_version_number(repo, new_version):
 
     new_git_tag = "v" + new_version
     for existing_tag in repo.tags:
-        if new_git_tag == existing_tag:
+        existing_tag_str = str(existing_tag)
+
+        if new_git_tag == existing_tag_str:
             sys.exit(f"Git release tag already exists: {new_git_tag}")
 
         # Split e.g. "v1.0.0" -> "1.0.0"
-        existing_version = existing_tag.split("v")[1]
+        existing_version = existing_tag_str.split("v")[1]
         if parse(new_version) <= parse(existing_version):
             sys.exit(f"New version {new_version} is not greater than existing tag {existing_tag}")