diff --git a/docs/Makefile b/docs/Makefile index 131624c5..25827017 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS ?= +SPHINXOPTS ?= -W --keep-going SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build diff --git a/docs/source/developers_guide/examples.md b/docs/source/developers_guide/examples.md index 7b6600eb..c3b74fe0 100644 --- a/docs/source/developers_guide/examples.md +++ b/docs/source/developers_guide/examples.md @@ -1,4 +1,4 @@ -## Examples +# Examples :::{note} Basic usage of examples is explained in the {ref}`getting-started` section. diff --git a/docs/source/elaboratable_wrapper.md b/docs/source/elaboratable_wrapper.md index 32e7f988..b0963ac1 100644 --- a/docs/source/elaboratable_wrapper.md +++ b/docs/source/elaboratable_wrapper.md @@ -1,6 +1,6 @@ # ElaboratableWrapper class -{class}`ElaboratableWrapper` encapsulates an Amaranth's Elaboratable and exposes an interface compatible with other wrappers which allows making connections with them. +{class}`topwrap.elaboratable_wrapper.ElaboratableWrapper` encapsulates an Amaranth's Elaboratable and exposes an interface compatible with other wrappers which allows making connections with them. Supplied elaboratable must contain a `signature` property and a conforming interface as specified by [Amaranth docs](https://amaranth-lang.org/rfcs/0002-interfaces.html). Ports' directionality, their names and widths are inferred from it. diff --git a/docs/source/fusesoc.md b/docs/source/fusesoc.md index 56a5a51e..142cce8d 100644 --- a/docs/source/fusesoc.md +++ b/docs/source/fusesoc.md @@ -2,13 +2,13 @@ Toprwap uses FuseSoC to automate project generation and build process. -A `Core` file is needed in order to generate a project. The file can be generated from a template using {class}`FuseSocBuilder` class. The `Core` file contains information about source files and synthesis tools. +A `Core` file is needed in order to generate a project. The file can be generated from a template using {class}`topwrap.fuse_helper.FuseSocBuilder` class. The `Core` file contains information about source files and synthesis tools. ## Core file template A template for the core file is bundled with Topwrap (`templates/core.yaml.j2`). You may need to edit the file to change the backend tool, set additional `Hooks` and change the FPGA part name or other parameters. -By default, {class}`FuseSocBuilder` searches for the template file in the directory you work in, so you should first copy the template into the project's location. +By default, {class}`topwrap.fuse_helper.FuseSocBuilder` searches for the template file in the directory you work in, so you should first copy the template into the project's location. ## Using the FuseSocBuilder diff --git a/docs/source/getting_started.md b/docs/source/getting_started.md index 47187a5b..4added37 100644 --- a/docs/source/getting_started.md +++ b/docs/source/getting_started.md @@ -31,7 +31,7 @@ pip3 install ".[topwrap-parse]" This section demonstrates the basic usage of Topwrap to generate IP wrappers and a top module. -1. Create {class}`IPWrapper` objects for every IP Core you want to use: +1. Create {class}`topwrap.ipwrapper.IPWrapper` objects for every IP Core you want to use: ```yaml ips: diff --git a/docs/source/helpers.md b/docs/source/helpers.md index df23b8de..b3f575fc 100644 --- a/docs/source/helpers.md +++ b/docs/source/helpers.md @@ -1,7 +1,7 @@ # Helpers ```{eval-rst} -.. autoclass:: topwrap.interface.InterfaceDef +.. autoclass:: topwrap.interface.InterfaceDefinition :members: .. automethod:: __init__ @@ -11,10 +11,6 @@ .. autofunction:: topwrap.interface.get_interface_by_name ``` -```{eval-rst} -.. autofunction:: topwrap.interface.get_interface_by_prefix -``` - ```{eval-rst} .. autoclass:: topwrap.config.Config :members: @@ -23,5 +19,5 @@ ``` ```{eval-rst} -.. autofunction:: topwrap.util.check_interface_compliance +.. autofunction:: topwrap.interface.check_interface_compliance ``` diff --git a/docs/source/ipconnect.md b/docs/source/ipconnect.md index 842b7942..bb628d80 100644 --- a/docs/source/ipconnect.md +++ b/docs/source/ipconnect.md @@ -1,6 +1,6 @@ # IPConnect class -Topwrap uses {class}`IPConnect` to encapsulate IP Cores in a module, and connect their wires and interfaces. +Topwrap uses {class}`topwrap.ipconnect.IPConnect` to encapsulate IP Cores in a module, and connect their wires and interfaces. After the object is created, IPs can be added using {code}`add_ip` method: @@ -16,7 +16,7 @@ ip.add_ip(dma) IPs are connected using {code}`make_connections` function. Ports and interfaces can be set as external input/output/inout with {code}`make_external_ports_interfaces` and retrieved with {code}`get_ports`. -For a wider example of using the {class}`IPConnect` see {ref}`Getting Started ` +For a wider example of using the {class}`topwrap.ipconnect.IPConnect` see {ref}`Getting Started ` ```{eval-rst} .. autoclass:: topwrap.ipconnect.IPConnect diff --git a/docs/source/ipwrapper.md b/docs/source/ipwrapper.md index d4c82fdb..d31a0b38 100644 --- a/docs/source/ipwrapper.md +++ b/docs/source/ipwrapper.md @@ -1,6 +1,6 @@ # IPWrapper class -{class}`IPWrapper` is the main class used to instantiate an IP Core and generate HDL wrapper. +{class}`topwrap.ipwrapper.IPWrapper` is the main class used to instantiate an IP Core and generate HDL wrapper. It's used to standardize names of ports that belong to interfaces to ease connecting multiple IPs. ```{eval-rst} diff --git a/topwrap/amaranth_helpers.py b/topwrap/amaranth_helpers.py index 5d8d92b3..4a6c1fdb 100644 --- a/topwrap/amaranth_helpers.py +++ b/topwrap/amaranth_helpers.py @@ -49,8 +49,9 @@ def __init__( """ Wraps a port, adding a new name and optionally slicing the signal - :param bounds[0:1]: upper and lower bounds of reference signal - :param bounds[2:3]: upper and lower bounds of internal port, + :param bounds: 4-element list where: + [0:1] - upper and lower bounds of reference signal, + [2:3] - upper and lower bounds of internal port, which are either the same as reference port, or a slice of the reference port