sphinx-rtl 0.1.0__py3-none-any.whl

sphinx-rtl/RTLDomain/RTLDomain.py

@@ -0,0 +1,6 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    25/09/2026
+#
+# Brief :   Import the RTL Domain to be used for all the RTL components.
+# ----------------------------------------------------------------------------

sphinx-rtl/RTLDomain/__init__.py

@@ -0,0 +1,6 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    25/09/2026
+#
+# Brief :   Import the RTL Domain to be used for all the RTL components.
+# ----------------------------------------------------------------------------

sphinx-rtl/__init__.py

@@ -0,0 +1,24 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    18/09/2026
+#
+# Brief :   Initialize sphinx to find our module
+# ----------------------------------------------------------------------------
+
+# Imports
+from .directive import RTLAutodocDirective
+
+
+# Setup
+def setup(app):
+
+    # Load the extensions
+    app.setup_extension("myst_parser")
+
+    # Add the name and aliases
+    app.add_directive("rtl-autodoc", RTLAutodocDirective)
+    app.add_directive("vhdl-autodoc", RTLAutodocDirective)
+    app.add_directive("sv-autodoc", RTLAutodocDirective)
+
+    # Return
+    return {"version": "0.1.0", "parallel_read_safe": True, "parallel_write_safe": True}

sphinx-rtl/config.py

@@ -0,0 +1,66 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    25/09/2026
+#
+# Brief :   Define the standard configurations elements to be used
+#           within the project.
+# ----------------------------------------------------------------------------
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RenderConfig:
+    """
+    Configure the rendering process, to be able to match the user needs.
+
+    Fields :
+        - inferClocks :         Do we need to infer clocks for the different ports ?
+        - inferResets :         Do we need to infer resets for the output ports ?
+        - inferIOs :            Do we need to infer IO for the different processes ?
+        - inferType:            Do we need to infer the component type (testbench, package, interface...) ?
+        - resolution :          Do we need to resolve the different modules ?
+        - mermaid :             Do we need to load the mermaid render from a CDN ?
+        - wavedrom :            Do we need to load wavefrom render from a CDN ?
+        - template :            Do we need to add a template instantiation at the end of the doc ?
+        - signals :             Do we need to show all signals in the doc ?
+        - internals :           Do we need to show all the internals (Processes, Enums, Imports ...) in the doc ? Setting this will also infer @nosignals.
+        - inferVendor :         Do we need to infer the vendor from the different modules ?
+        - vendor :              User available config to set the vendor manually.
+    """
+
+    # @noclocks
+    inferClocks: bool = True
+
+    # @noresets
+    inferResets: bool = True
+
+    # @noio
+    inferIOs: bool = True
+
+    # @notype
+    inferType: bool = True
+
+    # nosourceresolution
+    resolution: bool = True
+
+    # @nomermaid
+    mermaid: bool = True
+
+    # @wavedrom
+    wavedrom: bool = True
+
+    # @notemplate
+    template: bool = True
+
+    # @nosignals
+    signals: bool = True
+
+    # @nointernals:
+    internals: bool = True
+
+    # @novendors
+    inferVendor: bool = True
+
+    # @vendor Altera
+    vendor: str = ""

sphinx-rtl/directive.py

@@ -0,0 +1,108 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    18/09/2026
+#
+# Brief :   Define the top level parsing directive for Sphinx
+# ----------------------------------------------------------------------------
+
+# Imports
+import glob
+from pathlib import Path
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from .parsers import xVerilogParser, VHDLParser
+from .models import Component
+
+# Open the different parsers
+xVerilogTool = xVerilogParser()
+VHDLTool = VHDLParser()
+
+
+class RTLAutodocDirective(Directive):
+
+    # Configure the base class
+    required_arguments = 1
+    optional_arguments = 0
+    has_content = False
+
+    # Build the functions
+    def run(self):  # type: ignore
+
+        # Fetch the settings
+        env = self.state.document.settings.env
+
+        # Fetch the absolute path
+        search = Path(env.srcdir) / Path(self.arguments[0])
+
+        # Look for all files that could match:
+        if any(char in self.arguments[0] for char in ("*", "?", "[")):
+            matches = [
+                Path(p).resolve() for p in glob.glob(str(search), recursive=True)
+            ]
+        elif search.is_dir():
+            matches = [
+                p.resolve()
+                for p in search.iterdir()
+                if p.suffix.lower() in {".sv", ".v", ".vhd", ".vhdl"}
+            ]
+        else:
+            matches = [search.resolve()]
+
+        # Sort the files
+        matches = sorted(
+            [p for p in matches if p.is_file()],
+            key=lambda p: p.name.lower(),
+        )
+
+        # Exit if nothing was found
+        if not matches:
+            return [
+                self.state.document.reporter.warning(
+                    f"Could not find RTL file for the following pattern : {self.arguments[0]}",
+                    line=self.lineno,
+                )
+            ]
+
+        # Process all files
+        rendered_nodes: list[nodes.Node] = []
+
+        for match in matches:
+            env.note_dependency(str(match))
+
+            print("Processing ", match)
+
+            # Call the matching parser :
+            suffix = match.suffix.lower()
+            if suffix in [".sv", ".v"]:
+                component = xVerilogTool.parse(match)
+                rendered_nodes.extend(self._render(component))
+            elif suffix in [".vhd", ".vhdl"]:
+                # component = VHDLTool.parse(match)
+                # rendered_nodes.extend(self._render(component))
+                pass
+            else:
+                return self.state.reporter.error(
+                    f"Unknown format ({suffix}) for {match}.",
+                    line=self.lineno,
+                )
+
+        # Build the nodes from our RTL component:
+        return rendered_nodes
+
+    def _render(self, component: Component) -> list[nodes.Node]:
+        sec_id = nodes.make_id(f"rtl-{component.name}")
+        sec = nodes.section(ids=[sec_id])
+
+        sec += nodes.title(text=f"Module : {component.name}")
+
+        # Brief
+        if component.brief:
+            p_brief = nodes.paragraph()
+            p_brief += nodes.strong(text="Brief : ")
+            p_brief += nodes.Text(component.brief)
+            sec += p_brief
+
+        # TODO : Inject all the remaining details
+
+        return [sec]

sphinx-rtl/models.py

@@ -0,0 +1,339 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    18/09/2026
+#
+# Brief :   Define the standard interface between the different parsers for the
+#           different supported languages.
+# ----------------------------------------------------------------------------
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Element:
+    """
+    Basic config for an element to be defined. Shall not be used as it.
+    This ensure that Python will always find these elements in all class, regardless of the type.
+
+    Fields :
+        - name :            Store the name of the element.
+        - description :     Store the description of the element, typically the comment that is known to be attached for.
+        - line :            The line where the definition was found.
+    """
+
+    name: str = ""
+    description: str = ""
+    line: int = -1
+
+
+@dataclass
+class Parameter(Element):
+    """
+    Store the different values for a single parameter (or generic in VHDL) entry.
+
+    Fields :
+        - hdl_type :        The type of the Parameter.
+        - hdl_value :       The default value of the parameter (may also be the assigned value if called from a Module class)
+    """
+
+    hdl_type: str = ""
+    hdl_value: str = ""
+
+
+@dataclass
+class Port(Element):
+    """
+    Store the different values for a single port entry.
+
+    Fields :
+        - direction :       The direction of the port (input, output, inout...)
+        - hdl_type :        The type of the port, as passed on the file. May be standard or custom ports.
+        - hdl_size :        An array of N pairs of size, typically MSB:LSB. Single bit ports are expressed as "0", "0" (or any same value pair)
+        - hdl_value :       The default value given for the port.
+        - hdl_sync :        The clock to which this port is linked, in both reading and writing. This is inferred by the IR reduction pass.
+        - hdl_reset :       The reset port to which this port is linked, in writing only.
+    """
+
+    direction: str = ""
+    hdl_type: str = ""
+    hdl_size: list[str] = field(default_factory=list)
+    hdl_value: str = ""
+    hdl_sync: str = ""
+    hdl_reset: str = ""
+
+
+@dataclass
+class Enum(Element):
+    """
+    Store the different values for single enumeration (or type in VHDL) entry.
+
+    Fields :
+        - values :          The different elaboration resolved values for the enum.
+        - members :         The different members to be available on the file for this enum.
+    """
+
+    values: list[int] = field(default_factory=list)
+    members: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Import(Element):
+    """
+    Store the different values for a single import (Verilog Only) entry.
+
+    Fields :
+        - library :         The name of the element to be imported.
+        - element :         The name of the element to be imported within the provided library.
+    """
+
+    library: str = ""
+    element: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Signal(Element):
+    """
+    Store the different values for a single single reg / wire (or signal in VHDL) entry.
+
+    Fields :
+        hdl_type :          The type of the signal as wrote on the source file.
+        hdl_size :          The size of the signal, passed as N pairs of strings, typically under the form MSB,LSB. Single bit signals are expressed "x", "x" (or any value, they just must be equal)
+        hdl_value :         The value hold by this signal when declared.
+    """
+
+    hdl_type: str = ""
+    hdl_size: list[str] = field(default_factory=list)
+    hdl_value: str = ""
+
+
+@dataclass
+class Assignment(Element):
+    """
+    Store a constant assignment for a variable.
+
+    Fields :
+        - target :          The target signal name to be assigned.
+        - source :          The list of the source signals to be involved into this assignment.
+        - isComb :          Indicate that this assignment include more than a source, meaning the assignment require combinatorial logic. This will be evaluated for the output type.
+    """
+
+    target: str = ""
+    source: list[str] = field(default_factory=list)
+    isComb: bool = True
+
+
+@dataclass
+class Process(Element):
+    """
+    Store the different values for a single process / alway entry.
+
+    Fields :
+        - hdl_type :        The type of process, could be "comb" or "flipflop". This indicate the structure of the process for the IR.
+        - signals_write :   The signals to be affected by the process in write mode.
+        - signals :         The list of signals to be read by the process. Before the IR pass, this store all the keywords, they'll be passed to the reducer before being outputted.
+        - hdl_clock :       The list of signals to be seen as clocks for this process.
+        - hdl_reset :       The list of signals to be seen as resets for this process. They'll all include "rst" or "reset" in their name, in any place.
+    """
+
+    hdl_type: str = ""
+    signals_write: list[str] = field(default_factory=list)
+    signals: list[str] = field(default_factory=list)
+    hdl_clock: list[str] = field(default_factory=list)
+    hdl_reset: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Modport(Element):
+    """
+    Store a modport informations.
+    This class could only be used in xVerilog parser.
+
+    Fields :
+        signals :           The list of ports objects to be defined within the selected modport.
+    """
+
+    signals: list[Port] = field(default_factory=list)
+
+
+@dataclass
+class Interface(Element):
+    """
+    Store the config for an interface entry.
+
+    Fields :
+        - parameters :      The list of passed parameters to the interface.
+        - ports :           The list of ports of the interface.
+        - signals :         The list of signals within the interface.
+        - modports :        The list of modports for this inferace.
+    """
+
+    parameters: list[Parameter] = field(default_factory=list)
+    ports: list[Port] = field(default_factory=list)
+    signals: list[Signal] = field(default_factory=list)
+    modports: list[Modport] = field(default_factory=list)
+
+
+@dataclass
+class Module(Element):
+    """
+    Store the config for a known module, instantiated within the passed design.
+
+    Fields :
+        - entity :          The entity name of the included module.
+        - connections :     A list of string tuples that match the port name and the actual connection name.
+        - params :          The list of parameters passed to this module.
+        - isVendor :        Does the module target something that looks like a vendor primitive ?
+        - vendor :          The name of the vendor of this module, if applicable.
+    """
+
+    entity: str = ""
+    connections: list[tuple[str, str]] = field(default_factory=list)
+    params: list[Parameter] = field(default_factory=list)
+    isVendor: bool = False
+    vendor: str = ""
+
+
+@dataclass
+class Function(Element):
+    """
+    Store the config for a known function, instantiated within the passed design.
+    """
+
+    func_inputs: list[Port] = field(default_factory=list)
+    func_outputs: list[Port] = field(default_factory=list)
+
+
+@dataclass
+class FileInfo:
+    """
+    Store the different values for a single file info entry.
+    Most of these fields are targeted by a git repo to be fetched, therefore it is the most complete within a repo.
+    A fallback from the OS filesystem may be used.
+
+    Fields :
+        - name :            The name of the file
+        - path :            The path of the file
+        - creation_author : The name of the author which created the file, ie the name of the first committer for this file. This field remain unresolved when the FS fallback is used.
+        - creation_hash :   The hash of the first commit which affected this file. This field remain unresolved when the FS fallback is used.
+        - creation_date :   The date of the first commit which was affected by this file. This field remain unresolved when the FS fallback is used.
+        - edit_author :     The name of the latest author which committed this file. This field is resolved to the current user logged when building the doc. Therefore may be wrong for CICD based systems.
+        - edit_hash :       The hash of the latest commit which included this file. This field remain unresolved when the FS fallback is used.
+        - edit_date :       The date of the latest commit which included this file. This field is resolved to the latest date known to the OS.
+        - is_dirty :        Does this file contain changes that are not committed when building the doc ?
+        - message :         The latest commit message.
+    """
+
+    name: str = ""
+    path: str = ""
+    creation_author: str = ""
+    creation_hash: str = ""
+    creation_date: str = ""
+    edit_date: str = ""
+    edit_hash: str = ""
+    edit_author: str = ""
+    is_dirty: bool = False
+    message: str = ""
+
+
+@dataclass
+class ComponentConfig:
+    """
+    Store additional elements for the Component object, that are more
+    linked to the user config rather than pure HDL elements.
+
+    Fields :
+        - isTestbench :     Define the current component as a testbench. This change some behaviors when the rendering pass is done*.
+        - testbenchTarget : The name of the component to be tested. Only evaluated if this module is a testbench.
+        - isPackage :       Define the current component as a package. This does change some behaviors when the rendering pass is done*.
+        - isInterface:      Define the current component as an interface. This does change some behaviors when the rendering pass is done*.
+        - status :          The status of the component. Could be any string, but standard (beta, release, stable ...) shall be preferred.
+        - version :         The version of the module.
+        - task :            Insert here the current task this module is relevant to. Could be @task Project XX or @task Client YY
+        - copyright :       Is this module copyrighted to anything ?
+        - tags :            A list of free tags to be used anywhere.
+
+    * : Different elements may or may not be useful for the different kind of objects. Therefore, these flags are checking them
+        to configure the optimal render method for the current component.
+    """
+
+    # @testbench
+    isTestbench: bool = False
+
+    # @target module_xx
+    testbenchTarget: str = ""
+
+    # @package
+    isPackage: bool = False
+
+    # @interface
+    isInterface: bool = False
+
+    # @status released
+    status: str = "release"
+
+    # @version 1.0.0
+    version: str = "1.0.0"
+
+    # @task JIRA-928
+    task: str = ""
+
+    # @copyright Altera Corp.
+    copyright: str = ""
+
+    # @tags Done
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Component:
+    """
+    Store all the infos for a component. Include all infos to be shared.
+
+    Fields :
+        - file :            The FileInfo class that store all elements.
+        - name :            The name of the component to be used.
+        - brief :           The brief description of the component.
+        - details :         The long description of the component.
+        - config :          The extended config file to be used.
+        - comp_type :       The component type, to eventually be inferred by the IR.
+
+        - parameters :      The list of available parameters for this component.
+        - ports :           The list of module ports.
+        - enums :           The list of module enums.
+        - imports :         The list of imports for the module.
+        - signals :         The list of internal signals.
+        - process :         The list of internal process within the module.
+        - assigns :         The list of internal assignments.
+        - interfaces :      The list of available interfaces. Only exposed when this file describe at least an interface.
+        - modules :         The list of included elements within the design.
+        - functions :       The list of functions the element may define.
+
+        - flags :           The list of unresolved flags, to be passed to the render stage(s).
+    """
+
+    # File infos
+    file: FileInfo
+
+    # Basic infos
+    name: str = ""
+    brief: str = ""
+    details: str = ""
+    comp_type: str = ""
+
+    # Render config
+    config: ComponentConfig = field(default_factory=ComponentConfig)
+
+    # HDL elements
+    parameters: list[Parameter] = field(default_factory=list)
+    ports: list[Port] = field(default_factory=list)
+    enums: list[Enum] = field(default_factory=list)
+    imports: list[Import] = field(default_factory=list)
+    signals: list[Signal] = field(default_factory=list)
+    process: list[Process] = field(default_factory=list)
+    assigns: list[Assignment] = field(default_factory=list)
+    interfaces: list[Interface] = field(default_factory=list)
+    modules: list[Module] = field(default_factory=list)
+    functions: list[Function] = field(default_factory=list)
+
+    # Unknown flags
+    flags: list[str] = field(default_factory=list)

sphinx-rtl/parsers/PropertiesEngine/__init__.py

@@ -0,0 +1,7 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    25/09/2026
+#
+# Brief :   Handle the properties management of the different modules,
+#           under the name of the main parser.
+# ----------------------------------------------------------------------------

sphinx-rtl/parsers/VHDL.py

@@ -0,0 +1,39 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    18/09/2026
+#
+# Brief :   Build the standard VHDL parser.
+#
+# Require : GHDL
+# ----------------------------------------------------------------------------
+
+# Imports
+import shutil
+import logging
+from pathlib import Path
+
+from ..models import Component
+from .xParser import xParser
+
+# Logger config
+logger = logging.getLogger(__name__)
+
+
+class VHDLParser(xParser):
+    """
+    Define the standard VHDL Parser model.
+    Designed to be reused (can be openned only once and parse more than one file).
+    """
+
+    def __init__(self):
+        """
+        Init the VHDL parser for different operations.
+        """
+
+        super().__init__("ghdl")
+
+    def parse(self, file: Path):
+        """
+        Parse the passed file as VHDL, and output the built class.
+        """
+        pass

sphinx-rtl/parsers/VHDLFunctions/__init__.py

@@ -0,0 +1,6 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    24/09/2026
+#
+# Brief :   Assemble a sub element of the standard module for the VHDL.
+# ----------------------------------------------------------------------------

sphinx-rtl/parsers/__init__.py

@@ -0,0 +1,11 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    18/09/2026
+#
+# Brief :   Import the different parsers and assemble them into a
+#           properly formed package.
+# ----------------------------------------------------------------------------
+
+# Local imports
+from .xVerilog import xVerilogParser
+from .VHDL import VHDLParser

sphinx-rtl/parsers/cocotb/__init__.py

@@ -0,0 +1,6 @@
+# ----------------------------------------------------------------------------
+# Author :  l.heywang <leonard.heywang@proton.me>
+# Date :    25/09/2026
+#
+# Brief :   Assemble a sub element of the standard module for the cocotb.
+# ----------------------------------------------------------------------------