Updated documnetation for all sections of the chipflow.toml

Author: lanserge

docs/chipflow-toml-guide.rst

@@ -28,13 +28,33 @@ Let's start with a typical example:
 
 The ``project_name`` is a human-readable identifier for this project. If not set, the tool and library will use the project name configured in ``pyproject.toml``.
 
+``[chipflow.top]``
+------------------
+
+.. code-block:: TOML
+
+   [chipflow.top]
+   soc = "my_design.design:MySoC"
+
+This section outlines the design modules that need to be instantiated.
+A new top module will be automatically generated, incorporating all specified modules along with their interfaces.
+Each entry follows the format `<instance name> = <module class path>`.
+
+The instance name is the name the python object will be given in your design, and the :term:`module class path`
+
+.. glossary::
+
+   module class path
+       The module class path offers a way to locate Python objects as entry points.
+       It consists of a module's :term:`qualified name` followed by a colon (:) and then the :term:`qualified name` of the class within that module.
+
 ``[chipflow.steps]``
 --------------------
 
-The ``steps`` section allows overriding or addition to the standard steps available from `chipflow_lib`_.
+The ``steps`` section allows overriding or addition to the standard steps available from `chipflow_lib`.
 
 For example, if you want to override the standard silicon preparation step, you could derive from :class:`chipflow_lib.steps.silicon.SiliconStep`, add your custom functionality
-and add the following to your `chipflow.toml`, with the appropriate Python `qualified name`_ :
+and add the following to your `chipflow.toml`, with the appropriate :term:`module class path`:
 
 .. code-block:: TOML
 
@@ -44,8 +64,7 @@ and add the following to your `chipflow.toml`, with the appropriate Python `qual
 
 You probably won't need to change these if you're starting from an example repository.
 
-.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib]
-.. _qualified name: https://docs.python.org/3/glossary.html#term-qualified-name
+.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib
 
 
 ``[chipflow.clocks]``
@@ -57,8 +76,8 @@ You probably won't need to change these if you're starting from an example repos
    default = 'sys_clk'
 
 This section links the clock domains utilized in the design to specific pads.
-These pads need to be specified in the `[silicon.pads]`_ section with `type`_ equal to ``clock``.
-The ``default`` clock domain is associated with the Amaranth ``sync`` clock domain.
+These pads need to be specified in the `[silicon.pads]`_ section with the :term:type set to :term:clock.
+The ``default`` clock domain is associated with the Amaranth :any:`sync <lang-domains>` :ref:`clock domain <lang-clockdomains>`.
 Currently, only one ``default`` clock domain is supported.
 
 
@@ -71,7 +90,7 @@ Currently, only one ``default`` clock domain is supported.
    default = 'sys_rst_n'
 
 This section identifies the input pads designated for reset functionality.
-These pads need to be specified in the `[silicon.pads]`_ section with `type`_ equal to ``reset``.
+These pads need to be specified in the `[silicon.pads]`_ section with the :term:type set to :term:reset.
 The logic that synchronizes the reset signal with the clock will be generated automatically.
 
 ``[chipflow.silicon]``
@@ -104,7 +123,7 @@ Available processes
 +------------+------------+---------------------------+
 
 Available pad rings
----------------------------------
+-------------------
 
 +----------+-----------+--------------------+------------------------------------+
 | Pad ring | Pad count | Pad locations      | Notes                              |
@@ -118,13 +137,11 @@ Available pad rings
 +----------+-----------+--------------------+------------------------------------+
 
 
-
-
-_`[silicon.pads]`
-==================
+``[silicon.pads]``
+------------------
 
 The ``silicon.pads`` section lists special pads. In general you are unlikely to need to add to this.
-Each pad specified with the name used by the design and two parameters: `type`_ and `loc`_.
+Each pad specified with the name used by the design and two parameters: :term:type and :term:`loc`.
 
 .. code-block:: TOML
 
@@ -134,37 +151,30 @@ Each pad specified with the name used by the design and two parameters: `type`_
 
 In the above example two pads specified, ``sys_clk`` pad for clock input and ``sys_rst_n`` for reset.
 
-_`type`
--------
-
-The ``type`` for each pad can be set to one of:
-
-clock
-   External clock input.
-
-reset
-   External reset input.
+.. glossary::
 
-i
-   Input.
+   loc
+       This is the physical location of the pad on your chosen pad ring. How these are indexed varies by the pad ring.
 
-o
-   Output.
+   type
+       The :term:type for each pad can be set to one of :term:clock or :term:reset.
 
-io
-   Both input and output.
+   clock
+       External clock input.
 
-_`loc`
-------
+   reset
+       External reset input.
 
-This is the physical location of the pad on your chosen pad ring. How these are indexed varies by the pad ring.
 
-silicon.power
-=============
+``[silicon.power]``
+-------------------
 
-This section describes how the pads should be connected to the power available on the chosen process and package.
+This section outlines the connection of pads to the power supply available for the selected process and package.
+These pads are declared with the :term:type and :term:loc parameters, similar to the `[silicon.pads]`_ section.
+Note that in this context, the :term:type parameter can only be ``ground`` or ``power``.
 
 This is a work in progress, and currently you can use the defaults provided by customer support.
 
-
 .. _Caravel Harness: https://caravel-harness.readthedocs.io/en/latest/
+
+

docs/conf.py

@@ -80,15 +80,15 @@
 # Napoleon settings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
+napoleon_use_ivar = True
 napoleon_include_init_with_doc = True
-napoleon_include_private_with_doc = True
 napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_rtype = True
+napoleon_custom_sections = [
+    ("Arguments", "params_style"), # by default displays as "Parameters"
+    ("Attributes", "params_style"), # by default displays as "Variables", which is confusing
+    ("Members", "params_style"), # `amaranth.lib.wiring` signature members
+]
+
 
 rst_prolog = """
 .. role:: py(code)