Make Sphinx fail on warnings, fix all warnings

Internal-tag: [#53270]
Signed-off-by: Krzysztof Obłonczek <[email protected]>

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

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.

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.
 

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
 

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:

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
 ```

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 <getting-started>`
+For a wider example of using the {class}`topwrap.ipconnect.IPConnect` see {ref}`Getting Started <getting-started>`
 
 ```{eval-rst}
 .. autoclass:: topwrap.ipconnect.IPConnect

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}

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