Fix up docs generation

Author: robtaylor

chipflow_lib/platforms/utils.py

@@ -89,8 +89,9 @@ class _IOModelOptions(TypedDict):
 class IOModel(_IOModelOptions):
     """
     Options for IO Ports
+
     Attributes:
-        direction: Input, Output or Bidir
+        direction: `io.Direction.Input`, `io.Direction.Output` or `io.Direction.Bidir`
         width: width of port, default is 1
         all_have_oe: controls whether each output wire is associated with an individual Output Enable bit
             or a single OE bit will be used for entire port, the default value is False, indicating that a
@@ -1047,10 +1048,18 @@ def heartbeat(self) -> Dict[int, Pin]:
 }
 
 class Process(Enum):
+    """
+    IC manufacturing process
+    """
+    #: Skywater foundry open-source 130nm process
     SKY130 = "sky130"
+    #: GlobalFoundries open-source 130nm process
     GF180 = "gf180"
+    #: Pragmatic Semiconductor FlexIC process (old)
     HELVELLYN2 = "helvellyn2"
+    #: GlobalFoundries 130nm BCD process
     GF130BCD = "gf130bcd"
+    #: IHP open source 130nm SiGe Bi-CMOS process
     IHP_SG13G2 = "ihp_sg13g2"
 
     def __str__(self):

docs/chipflow-toml-guide.rst

@@ -14,34 +14,58 @@ Let's start with a typical example:
    # Assert that example-chipflow.toml matches the current config schema. If
    # this test fails, then its likely that the content in this file will need
    # to be updated.
-   from chipflow_lib import _parse_config_file
+   from chipflow_lib.config import _parse_config_file
    _parse_config_file("docs/example-chipflow.toml")
 
-``[chipflow]``
---------------
+``[chipflow]`` table
+--------------------
+
+|required|
+
+The top level configuration for inputs to the ChipFlow tools.
+
+
+project_name
+============
+
+|required|
+
+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``.
 
 .. code-block:: TOML
 
    [chipflow]
-   project_name = "my_project"
+   project_name = 'my_project'
 
+clock_domains
+=============
 
-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``.
+|optional|
 
-``[chipflow.top]``
-------------------
+A list of top-level clock domains for your design. If omitted, defaults to the `Amaranth` default ``sync``, and sync is always assumed to be the name of the core clock for bringup.
 
 .. code-block:: TOML
 
-   [chipflow.top]
-   soc = "my_design.design:MySoC"
+   [chipflow]
+   clock_domains = ['sync', 'peripheral']
+
+
+``[chipflow.top]`` table
+------------------------
+
+|required|
 
 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`
 
+.. code-block:: TOML
+
+   [chipflow.top]
+   soc = "my_design.design:MySoC"
+
 .. glossary::
 
    module class path
@@ -50,8 +74,10 @@ The instance name is the name the python object will be given in your design, an
 
 .. _chipflow-toml-steps:
 
-``[chipflow.steps]``
---------------------
+``[chipflow.steps]`` table
+--------------------------
+
+|optional|
 
 The ``steps`` section allows overriding or addition to the standard steps available from `chipflow_lib`.
 
@@ -69,27 +95,15 @@ You probably won't need to change these if you're starting from an example repos
 .. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib
 
 
-Clock Definitions
------------------
-
-The clock pins to be allocation on the package are determined from the top level clock domains exposed by components in `[chipflow.top]`.
-
-
-
-``[chipflow.resets]``
----------------------
+``[chipflow.silicon]``
+----------------------
 
-.. code-block:: TOML
+|required|
 
-   [chipflow.resets]
-   default = 'sys_rst_n'
+The ``silicon`` section sets the Foundry ``process`` (i.e. PDK) that we are targeting for manufacturing, and the physical ``package`` (including pad ring) we want to place our design inside.
 
-This section identifies the input pads designated for reset functionality.
-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.
+You'll choose the ``process`` and ``package`` based in the requirements of your design.
 
-``[chipflow.silicon]``
-----------------------
 
 .. code-block:: TOML
 
@@ -98,12 +112,12 @@ The logic that synchronizes the reset signal with the clock will be generated au
    package = "pga144"
 
 
-The ``silicon`` section sets the Foundry ``process`` (i.e. PDK) that we are targeting for manufacturing, and the physical ``package`` (including pad ring) we want to place our design inside.
+process
+=======
 
-You'll choose the ``process`` and ``package`` based in the requirements of your design.
+|required|
 
-Available processes
--------------------
+Foundry process to use
 
 +------------+------------+---------------------------+
 || Process   || Supported || Notes                    |
@@ -118,8 +132,13 @@ Available processes
 | ihp_sg13g2 | pga144     | IHP SG13G2 130nm SiGe     |
 +------------+------------+---------------------------+
 
-Available Package Definitions
------------------------------
+
+package
+=======
+
+|required|
+
+The form of IC packaging to use
 
 +----------+-----------+--------------------+------------------------------------+
 | Pad ring | Pad count | Pad locations      | Notes                              |

docs/conf.py

@@ -34,6 +34,9 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'autoapi.extension',
+    'sphinxcontrib.autoprogram',
+    'sphinxcontrib.autodoc_pydantic',
+    'sphinx_design',
 ]
 
 html_theme = 'furo'
@@ -98,5 +101,10 @@
    :language: python
 """
 
+rst_epilog = """
+.. |required| replace:: :bdg-primary-line:`Required`
+.. |optional| replace:: :bdg-secondary-line:`Optional`
+"""
+
 # -- Options for EPUB output
 epub_show_urls = 'footnote'

pdm.lock

@@ -63,10 +63,6 @@ include = [
 select = ["E4", "E7", "E9", "F", "W291", "W293"]
 ignore = ['F403', 'F405']
 
-
-
-
-
 [tool.pdm.version]
 source = "scm"
 
@@ -92,6 +88,10 @@ dev = [
     "tomli-w>=1.2.0",
     "pyright>=1.1.392",
     "amaranth-stubs>=0.1.1",
+    "sphinxcontrib-autoprogram>=0.1.9",
+    "sphinx-autodoc-typehints>=2.3.0",
+    "autodoc-pydantic>=2.2.0",
+    "sphinx-design>=0.6.1",
 ]
 
 [tool.pytest.ini_options]