doc cleanup

chipflow_lib/__init__.py

@@ -1,3 +1,7 @@
+"""
+Chipflow library
+"""
+
 import importlib.metadata
 import os
 import sys
@@ -7,7 +11,6 @@
 
 __version__ = importlib.metadata.version("chipflow_lib")
 
-
 class ChipFlowError(Exception):
     pass
 

chipflow_lib/platforms/__init__.py

@@ -1,3 +1,15 @@
+"""
+Platform definititions
+----------------------
+
+This module defines the functionality you use in you code to target the ChipFlow platform
+
+"""
+
 from .silicon import *
 from .sim import *
 from .utils import *
+
+__all__ = ['PIN_ANNOTATION_SCHEMA', 'PinSignature',
+           'OutputPinSignature', 'InputPinSignature', 'BidirPinSignature',
+           'load_pinlock', "PACKAGE_DEFINITIONS", 'top_interfaces']

chipflow_lib/platforms/utils.py

@@ -99,13 +99,24 @@ def __init__(self, direction: io.Direction, width: int = 1, all_have_oe: bool =
         super().__init__(sig)
 
     @property
-    def direction(self):
+    def direction(self) -> io.Direction:
+        "The direction of the IO port"
         return self._direction
 
-    def width(self):
+    def width(self) -> int:
+        "The width of the IO port, in wires"
         return self._width
 
-    def options(self):
+    def options(self) -> dict:
+        """
+        Options set on the io port at construction
+
+        Valid options are:
+            "all_have_oe": For a bidirectional port, each wire can
+            have it's direction dynamically controlled seperately,
+            so each wire also has a corresponding Output Enable wire.
+            "init": the initial value that this io port will have at power-up and reset.
+        """
         return self._options
 
     def annotations(self, *args):

docs/conf.py

@@ -4,6 +4,8 @@
 # Add parent folder to path so we can pick up module
 import os
 import sys
+from pprint import pformat
+
 sys.path.insert(0, os.path.abspath('../../chipflow_lib'))
 
 from chipflow_lib import __version__
@@ -25,51 +27,39 @@
 # -- General configuration
 
 extensions = [
-    'sphinx.ext.duration',
-    'sphinx.ext.doctest',
     'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc.typehints',
+    'sphinx.ext.doctest',
+    'sphinx.ext.duration',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
     'autoapi.extension',
-    'sphinx.ext.napoleon'
 ]
 
-html_theme = 'sphinx_book_theme'
+html_theme = 'furo'
 html_logo = '_static/chipflow-logo.svg'
 html_title = "ChipFlow Platform Documentation"
 
-
-html_sidebars = {
-    '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
-    ]
-}
-
-html_static_path = ['_static']
-
-html_theme_options = {
-    "home_page_in_toc": True,
-    "repository_url": "https://github.com/ChipFlow/chipflow-lib",
-    "repository_branch": "master",
-    "path_to_docs": "docs",
-    "use_repository_button": True,
-    "use_edit_page_button": True,
-    "use_issues_button": True,
-    "show_navbar_depth": 3,
-    # "announcement": "<b>v3.0.0</b> is now out! See the Changelog for details",
-}
-
 autodoc_typehints = 'description'
 
-autoapi_dirs = ["../chipflow_lib"]
+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',
-    'undoc-members',
     'show-inheritance',
     'show-module-summary',
     'imported-members',
 ]
 
+# Exclude autoapi templates
+exclude_patterns = [autoapi_template_dir]
+
 intersphinx_mapping = {
     'py': ('https://docs.python.org/3/', None),
     'amaranth': ('https://amaranth-lang.org/docs/amaranth/v0.5.4/', None),

docs/index.rst

@@ -11,6 +11,8 @@ ChipFlow Library Documentation
 
 
 .. toctree::
+   :maxdepth: 2
+   :caption: Contents:
 
    chipflow-toml-guide
-
+   autoapi/index