Disable AutoAPI generation due to CI import issues

AutoAPI is encountering "Unable to read file" warnings for all modules
in the CI environment, preventing documentation from building. The root
cause appears to be related to module import resolution in CI that does
not occur locally.

Adds manual API documentation using sphinx.ext.autodoc directives to
ensure comprehensive API coverage.

Changes:
- Set autoapi_generate_api_docs = False in docs/conf.py
- Removed duplicate ../chipflow_lib/platforms from autoapi_dirs
- Removed all autoapi references from documentation files
- Documentation now relies on manual API documentation in platform-api.rst
- Add api to docs/platform-api.rst
- Organized API docs by category: Platforms, Build Steps, IO Signatures,
  IO Configuration, Utilities, and Constants

Co-Authored-By: Claude <noreply@anthropic.com>

Author: robtaylor

docs/architecture.rst

@@ -116,7 +116,7 @@ When you run ``chipflow pin lock``:
 
 The ``pins.lock`` file maps abstract interface names to concrete package pin locations:
 
-.. code-block:: json
+.. code-block:: javascript
 
     {
       "uart.tx": {"pin": "42", "loc": "A12"},
@@ -270,7 +270,7 @@ The annotation system is central to how ChipFlow propagates metadata:
 
    Pydantic TypeAdapter generates JSON schema from TypedDict:
 
-   .. code-block:: json
+   .. code-block:: javascript
 
        {
          "$schema": "https://json-schema.org/draft/2020-12/schema",

docs/conf.py

@@ -33,7 +33,7 @@
     'sphinx.ext.duration',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
-    'autoapi.extension',
+    # 'autoapi.extension',  # Temporarily disabled due to CI import issues
     'sphinxcontrib.autoprogram',
     'sphinxcontrib.autodoc_pydantic',
     'sphinx_design',
@@ -55,24 +55,37 @@
 
 autodoc_typehints = 'description'
 
-autoapi_dirs = [
-        "../chipflow_lib/platforms",
-        "../chipflow_lib",
-        ]
-autoapi_generate_api_docs = True
-autoapi_template_dir = "_templates/autoapi"
-# autoapi_verbose_visibility = 2
-autoapi_keep_files = True
-autoapi_options = [
-    'members',
-    'show-inheritance',
-    'show-module-summary',
-    'imported-members',
-]
-
-# Exclude autoapi templates and in-progress stuff
+# AutoAPI configuration - temporarily disabled due to CI import issues
+#
+# AutoAPI is encountering "Unable to read file" errors for ALL Python modules
+# in the CI environment, preventing it from generating any API documentation.
+# This appears to be related to import-time issues during the refactoring work.
+#
+# Root cause investigation needed:
+# - Possible circular imports preventing module loading
+# - Import-time side effects that fail in CI but not locally
+# - Python path or module resolution differences in CI
+#
+# Workaround: Using manual sphinx.ext.autodoc directives in platform-api.rst
+# TODO: Re-enable AutoAPI once import issues are resolved
+#
+# autoapi_dirs = [
+#         "../chipflow_lib",
+#         ]
+# autoapi_generate_api_docs = False
+# autoapi_template_dir = "_templates/autoapi"
+# # autoapi_verbose_visibility = 2
+# autoapi_keep_files = True
+# autoapi_options = [
+#     'members',
+#     'show-inheritance',
+#     'show-module-summary',
+#     'imported-members',
+# ]
+
+# Exclude in-progress stuff and template files
 exclude_patterns = [
-    autoapi_template_dir,
+    "_templates",  # Exclude template files from being read as RST
     "unfinished",
 ]
 

docs/contributor-pin-signature-internals.rst

@@ -779,4 +779,3 @@ See Also
 --------
 
 - :doc:`using-pin-signatures` - User-facing guide for using pin signatures
-- :doc:`autoapi/chipflow_lib/platform/index` - Full platform API reference

docs/index.rst

@@ -15,7 +15,6 @@ It is developed at https://github.com/chipFlow/chipflow-lib/ and licensed `BSD 2
    chipflow-toml-guide
    chipflow-commands
    using-pin-signatures
-   API Reference <autoapi/index>
    platform-api
 
 .. toctree::

docs/platform-api.rst

@@ -3,15 +3,165 @@ Platform API Reference
 
 This page documents the complete public API of the ``chipflow_lib.platform`` module.
 
-For auto-generated documentation, see :doc:`autoapi/chipflow_lib/platform/index`.
+All symbols listed here are re-exported from submodules for convenience and can be imported directly from ``chipflow_lib.platform``.
 
-Re-exported Symbols
--------------------
-
-The following symbols are re-exported from submodules for convenience:
+Platforms
+---------
 
 .. autoclass:: chipflow_lib.platform.sim.SimPlatform
    :members:
    :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.silicon.SiliconPlatform
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.silicon.SiliconPlatformPort
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.software.SoftwarePlatform
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Build Steps
+-----------
+
+.. autoclass:: chipflow_lib.platform.base.StepBase
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.sim_step.SimStep
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.silicon_step.SiliconStep
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.software_step.SoftwareStep
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.board_step.BoardStep
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+IO Signatures
+-------------
+
+Base IO Signatures
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: chipflow_lib.platform.io.iosignature.IOSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.iosignature.OutputIOSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.iosignature.InputIOSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.iosignature.BidirIOSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Protocol-Specific Signatures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: chipflow_lib.platform.io.signatures.UARTSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.signatures.GPIOSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.signatures.SPISignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.signatures.I2CSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.signatures.QSPIFlashSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.signatures.JTAGSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Software Integration
+~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: chipflow_lib.platform.io.signatures.SoftwareDriverSignature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.signatures.SoftwareBuild
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 .. autofunction:: chipflow_lib.platform.io.signatures.attach_data
+
+IO Configuration
+----------------
+
+.. autoclass:: chipflow_lib.platform.io.iosignature.IOModel
+   :members:
+   :undoc-members:
+
+.. autoclass:: chipflow_lib.platform.io.iosignature.IOModelOptions
+   :members:
+   :undoc-members:
+
+.. autoclass:: chipflow_lib.platform.io.iosignature.IOTripPoint
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: chipflow_lib.platform.io.sky130.Sky130DriveMode
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Utility Functions
+-----------------
+
+.. autofunction:: chipflow_lib.platform.base.setup_amaranth_tools
+
+.. autofunction:: chipflow_lib.platform.utils.top_components
+
+.. autofunction:: chipflow_lib.platform.utils.get_software_builds
+
+Constants
+---------
+
+.. autodata:: chipflow_lib.platform.io.iosignature.IO_ANNOTATION_SCHEMA
+   :annotation:

docs/using-pin-signatures.rst

@@ -399,5 +399,4 @@ See Also
 --------
 
 - :doc:`chipflow-toml-guide` - Configuring your ChipFlow project
-- :doc:`autoapi/chipflow_lib/platform/index` - Platform API reference
 - :doc:`platform-api` - Complete platform API including SimPlatform and attach_data