docs: add Attribute and Members sections, and :py: role.

Author: jfng

amaranth_soc/csr/bus.py

@@ -74,16 +74,16 @@ class Signature(wiring.Signature):
         access : :class:`Element.Access`
             Register access mode.
 
-        Attributes
-        ----------
-        r_data : :pc:`unsigned(width)`
+        Members
+        -------
+        r_data : :py:`unsigned(width)`
             Read data. Must be always valid, and is sampled when ``r_stb`` is asserted.
-        r_stb : :pc:`unsigned(1)`
+        r_stb : :py:`unsigned(1)`
             Read strobe. Registers with read side effects should perform the read side effect when
             this strobe is asserted.
-        w_data : :pc:`unsigned(width)`
+        w_data : :py:`unsigned(width)`
             Write data. Valid only when ``w_stb`` is asserted.
-        w_stb : :pc:`unsigned(1)`
+        w_stb : :py:`unsigned(1)`
             Write strobe. Registers should update their value or perform the write side effect when
             this strobe is asserted.
 
@@ -215,21 +215,21 @@ class Signature(wiring.Signature):
     data_width : :class:`int`
         Data width. Registers are accessed in ``data_width`` sized chunks.
 
-    Attributes
-    ----------
-    addr : :pc:`unsigned(addr_width)`
+    Members
+    -------
+    addr : :py:`unsigned(addr_width)`
         Address for reads and writes.
-    r_data : :pc:`unsigned(data_width)`
+    r_data : :py:`unsigned(data_width)`
         Read data. Valid on the next cycle after ``r_stb`` is asserted. Otherwise, zero. (Keeping
         read data of an unused interface at zero simplifies multiplexers.)
-    r_stb : :pc:`unsigned(1)`
+    r_stb : :py:`unsigned(1)`
         Read strobe. If ``addr`` points to the first chunk of a register, captures register value
         and causes read side effects to be performed (if any). If ``addr`` points to any chunk
         of a register, latches the captured value to ``r_data``. Otherwise, latches zero
         to ``r_data``.
-    w_data : :pc:`unsigned(data_width)`
+    w_data : :py:`unsigned(data_width)`
         Write data. Must be valid when ``w_stb`` is asserted.
-    w_stb : :pc:`unsigned(1)`
+    w_stb : :py:`unsigned(1)`
         Write strobe. If ``addr`` points to the last chunk of a register, writes captured value
         to the register and causes write side effects to be performed (if any). If ``addr`` points
         to any chunk of a register, latches ``w_data`` to the captured value. Otherwise, does
@@ -453,9 +453,9 @@ class Multiplexer(wiring.Component):
         Maximum number of CSR registers that can share a chunk of a shadow register.
         Optional. If ``None``, any number of CSR registers can share a shadow chunk.
 
-    Attributes
-    ----------
-    bus : :class:`Interface`
+    Members
+    -------
+    bus : :class:`Signature`
         CSR bus providing access to registers.
     """
 
@@ -759,9 +759,9 @@ class Decoder(wiring.Component):
     name : :class:`str`
         Window name. Optional. See :class:`.MemoryMap`.
 
-    Attributes
-    ----------
-    bus : :class:`Interface`
+    Members
+    -------
+    bus : :class:`Signature`
         CSR bus providing access to subordinate buses.
     """
     def __init__(self, *, addr_width, data_width, alignment=0, name=None):

amaranth_soc/csr/reg.py

@@ -70,23 +70,23 @@ def writable(self):
     class Signature(wiring.Signature):
         """CSR register field port signature.
 
-        Parameters
-        ----------
+        Arguments
+        ---------
         shape : :ref:`shape-castable <lang-shapecasting>`
             Shape of the field.
         access : :class:`FieldPort.Access`
             Field access mode.
 
-        Attributes
-        ----------
-        r_data : :pc:`unsigned(shape)`
+        Members
+        -------
+        r_data : :py:`unsigned(shape)`
             Read data. Must always be valid, and is sampled when ``r_stb`` is asserted.
-        r_stb : :pc:`unsigned(1)`
+        r_stb : :py:`unsigned(1)`
             Read strobe. Fields with read side effects should perform them when this strobe is
             asserted.
-        w_data : :pc:`unsigned(shape)`
+        w_data : :py:`unsigned(shape)`
             Write data. Valid only when ``w_stb`` is asserted.
-        w_stb : :pc:`unsigned(1)`
+        w_stb : :py:`unsigned(1)`
             Write strobe. Fields should update their value or perform the write side effect when
             this strobe is asserted.
 
@@ -256,9 +256,9 @@ class FieldAction(wiring.Component):
         Signature members. Optional, defaults to ``()``. A :class:`FieldPort.Signature` member
         named 'port' and oriented as input is always present in addition to these members.
 
-    Attributes
-    ----------
-    port : :class:`FieldPort`
+    Members
+    -------
+    port : :class:`FieldPort.Signature`
         Field port.
 
     Raises
@@ -403,8 +403,8 @@ def flatten(self):
 class FieldActionArray(Sequence):
     """An array of CSR register fields.
 
-    Parameters
-    ----------
+    Arguments
+    ---------
     fields : :class:`list` of (:class:`Field` or :class:`dict` or :class:`list`)
         Register fields. Fields are instantiated according to their type:
 
@@ -491,9 +491,9 @@ class Register(wiring.Component):
         depending on its type (:class:`dict`, :class:`list`, or :class:`Field`).
     {arguments}
 
-    Attributes
-    ----------
-    element : :class:`Element`
+    Members
+    -------
+    element : :class:`Element.Signature`
         Interface between this :class:`Register` and a CSR bus primitive.
 
     Attributes
@@ -890,9 +890,9 @@ class Bridge(wiring.Component):
     memory_map : :class:`.MemoryMap`
         Memory map of CSR registers.
 
-    Attributes
-    ----------
-    bus : :class:`..bus.Interface`
+    Members
+    -------
+    bus : :class:`..bus.Signature`
         CSR bus providing access to the contents of ``memory_map``.
 
     Raises

amaranth_soc/gpio.py

@@ -43,13 +43,13 @@ class PinMode(enum.Enum, shape=unsigned(2)):
 class PinSignature(wiring.Signature):
     """GPIO pin signature.
 
-    Attributes
-    ----------
-    i : :pc:`unsigned(1)`
+    Members
+    -------
+    i : :py:`unsigned(1)`
         Input.
-    o : :pc:`unsigned(1)`
+    o : :py:`unsigned(1)`
         Output.
-    oe : :pc:`unsigned(1)`
+    oe : :py:`unsigned(1)`
         Output enable.
     """
     def __init__(self):
@@ -77,13 +77,13 @@ class Peripheral(wiring.Component):
         Number of synchronization stages between pin inputs and the :class:`~Peripheral.Input`
         register. Optional. Defaults to ``2``.
 
-    Attributes
-    ----------
-    bus : :class:`.csr.bus.Interface`
+    Members
+    -------
+    bus : :class:`.csr.bus.Signature`
         CSR bus interface providing access to registers.
-    pins : :class:`list` of :class:`wiring.PureInterface` of :class:`PinSignature`
+    pins : :class:`PinSignature` array of size ``pin_count``
         GPIO pin interfaces.
-    alt_mode : :pc:`unsigned(pin_count)`
+    alt_mode : :py:`unsigned(pin_count)`
         Indicates which members of the :attr:`Peripheral.pins` array are in alternate mode.
 
     Raises

amaranth_soc/wishbone/bus.py

@@ -60,39 +60,39 @@ class Signature(wiring.Signature):
         Selects additional signals that will be a part of this interface.
         Optional.
 
-    Attributes
-    ----------
-    adr : :pc:`unsigned(addr_width)`
+    Members
+    -------
+    adr : :py:`unsigned(addr_width)`
         Corresponds to Wishbone signal ``ADR_O`` (initiator) or ``ADR_I`` (target).
-    dat_w : :pc:`unsigned(data_width)`
+    dat_w : :py:`unsigned(data_width)`
         Corresponds to Wishbone signal ``DAT_O`` (initiator) or ``DAT_I`` (target).
-    dat_r : :pc:`unsigned(data_width)`
+    dat_r : :py:`unsigned(data_width)`
         Corresponds to Wishbone signal ``DAT_I`` (initiator) or ``DAT_O`` (target).
-    sel : :pc:`unsigned(data_width // granularity)`
+    sel : :py:`unsigned(data_width // granularity)`
         Corresponds to Wishbone signal ``SEL_O`` (initiator) or ``SEL_I`` (target).
-    cyc : :pc:`unsigned(1)`
+    cyc : :py:`unsigned(1)`
         Corresponds to Wishbone signal ``CYC_O`` (initiator) or ``CYC_I`` (target).
-    stb : :pc:`unsigned(1)`
+    stb : :py:`unsigned(1)`
         Corresponds to Wishbone signal ``STB_O`` (initiator) or ``STB_I`` (target).
-    we : :pc:`unsigned(1)`
+    we : :py:`unsigned(1)`
         Corresponds to Wishbone signal ``WE_O``  (initiator) or ``WE_I``  (target).
-    ack : :pc:`unsigned(1)`
+    ack : :py:`unsigned(1)`
         Corresponds to Wishbone signal ``ACK_I`` (initiator) or ``ACK_O`` (target).
-    err : :pc:`unsigned(1)`
+    err : :py:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``ERR_I`` (initiator) or ``ERR_O`` (target).
-    rty : :pc:`unsigned(1)`
+    rty : :py:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``RTY_I`` (initiator) or ``RTY_O`` (target).
-    stall : :pc:`unsigned(1)`
+    stall : :py:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``STALL_I`` (initiator) or ``STALL_O`` (target).
-    lock : :pc:`unsigned(1)`
+    lock : :py:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``LOCK_O`` (initiator) or ``LOCK_I`` (target).
         Amaranth-SoC Wishbone support assumes that initiators that don't want bus arbitration to
         happen in between two transactions need to use ``lock`` feature to guarantee this. An
         initiator without the ``lock`` feature may be arbitrated in between two transactions even
         if ``cyc`` is kept high.
-    cti : :pc:`unsigned(1)`
+    cti : :py:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``CTI_O`` (initiator) or ``CTI_I`` (target).
-    bte : :pc:`unsigned(1)`
+    bte : :py:`unsigned(1)`
         Optional. Corresponds to Wishbone signal ``BTE_O`` (initiator) or ``BTE_I`` (target).
 
     Raises
@@ -377,9 +377,9 @@ class Decoder(wiring.Component):
     name : :class:`str`
         Window name. Optional. See :class:`.MemoryMap`.
 
-    Attributes
-    ----------
-    bus : :class:`Interface`
+    Members
+    -------
+    bus : :class:`Signature`
         Wishbone bus providing access to subordinate buses.
     """
     def __init__(self, *, addr_width, data_width, granularity=None, features=frozenset(),
@@ -543,9 +543,9 @@ class Arbiter(wiring.Component):
     features : iterable of :class:`Feature`
         Optional signal set. See :class:`Signature`.
 
-    Attributes
-    ----------
-    bus : :class:`Interface`
+    Members
+    -------
+    bus : :class:`Signature`
         Shared Wishbone bus.
     """
     def __init__(self, *, addr_width, data_width, granularity=None, features=frozenset()):

docs/conf.py

@@ -39,13 +39,17 @@
 napoleon_use_ivar = True
 napoleon_include_init_with_doc = True
 napoleon_include_special_with_doc = True
+napoleon_custom_sections = [
+    ("Attributes", "params_style"), # by default displays as "Variables", which is confusing
+    ("Members", "params_style"), # `lib.wiring` signature members
+]
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
 html_css_files = ["custom.css"]
 html_logo = "_static/logo.png"
 
 rst_prolog = """
-.. role:: pc(code)
+.. role:: py(code)
    :language: python
 """