Incorporate chipflow-lib changes and tidy up

.github/workflows/deploy-docs-internal.yml

@@ -9,6 +9,7 @@ jobs:
 
   deploy-internal:
     runs-on: ubuntu-latest
+    needs: build-docs
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.gitignore

@@ -160,3 +160,6 @@ cython_debug/
 
 # pdm
 .pdm-python
+
+**/.claude/settings.local.json
+/vendor

README.md

@@ -1,16 +1,17 @@
 # ChipFlow documentation
 
-ChipFlow documentation repository, publishing to the
-[chipflow.github.io repository](https://github.com/ChipFlow/chipflow.github.io/)
-via GitHub actions.
+ChipFlow documentation repository, publishing to
+https://chipflow-docs.docs.chipflow-infra.com via GitHub actions.
+
+Releases are published to https://docs.chipflow.io
 
 
 ## Build and view docs locally
 
-Install Poetry into your environment if you don't have it already:
+Install PDM into your environment if you don't have it already:
 
 ```bash
-pip3 install pipx 
+pip3 install pipx
 pipx install pdm
 ```
 
@@ -23,13 +24,13 @@ pdm install
 Build the documentation locally:
 
 ```bash
-pdm run build
+pdm docs
 ```
 
 Automatically rebuild the documentation on change and preview them at the same time:
 
 ```bash
-pdm run autobuild
+pdm autodocs
 ```
 
 In your web browser go to http://localhost:8000 to see the documentation.

docs/source/conf.py

@@ -1,5 +1,28 @@
 # Configuration file for the Sphinx documentation builder.
+import os
+import sys
 from pathlib import Path
+from itertools import starmap
+
+top_path = Path('../../')
+sys.path.append(str((top_path / 'tools').absolute()))
+
+from tools import copy_docs
+
+# Repos we will be assembling
+repos = [
+    ('amaranth-lang/amaranth', 'tags/v0.5.4'),
+    ('chipflow/amaranth-soc', 'origin/reference-docs-chipflow'),
+    ('chipflow/chipflow-lib', 'origin/main')
+]
+
+# copy in the doc sources from our repos
+repo_list = copy_docs(repos)
+
+# add our repos to path
+for r in repo_list:
+    sys.path.append(str(r))
+
 # -- Project information
 
 project = 'ChipFlow'
@@ -10,27 +33,23 @@
 version = '0.1.0'
 
 # -- General configuration
-top_dir = Path(__file__).parent / ".." / ".."
 extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc.typehints',
     'sphinx.ext.duration',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.autosummary',
     'sphinx_copybutton',
     'myst_parser',
     'sphinx.ext.todo',
-    'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
     'sphinx_rtd_theme',
     'sphinxcontrib.platformpicker',
     'sphinxcontrib.yowasp_wavedrom',
-    'sphinx.ext.autodoc',
     'sphinxext.rediraffe',
+    'autoapi.extension',
 ]
-"""
-    "sphinx_design",
-    "sphinx_design_elements",
-"""
 
 rst_prolog = """
 .. role:: amaranth
@@ -43,24 +62,57 @@
    :language: python
 """
 
+html_theme = 'furo'
+html_logo = 'chipflow-lib/_assets/chipflow-logo.svg'
+html_title = "ChipFlow Platform Documentation"
+html_static_path = ['chipflow-lib/_assets', 'amaranth/_static', 'amaranth-soc/_static']
+
+html_theme_options = {
+    "dark_css_variables": {
+        "admonition-font-size": "0.9 rem",
+    },
+    "light_css_variables": {
+        "admonition-font-size": "0.9 rem",
+    },
+}
+
+autodoc_typehints = 'description'
+
+autoapi_dirs = [
+        top_path / "vendor/chipflow-lib/chipflow_lib/platforms",
+        top_path / "vendor/chipflow-lib/chipflow_lib",
+        ]
+autoapi_generate_api_docs = True
+autoapi_template_dir = "chipflow-lib/_templates/autoapi"
+# autoapi_verbose_visibility = 2
+autoapi_keep_files = True
+autoapi_options = [
+    'members',
+    'show-inheritance',
+    'show-module-summary',
+    'imported-members',
+]
+autoapi_root = "chipflow-lib/autoapi"
+
+# Exclude autoapi templates and in-progress stuff
+exclude_patterns = [
+    autoapi_template_dir,
+    "chipflow-lib/unfinished",
+    "amaranth/cover.rst",
+    "amaranth-soc/cover.rst",
+]
+
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
 }
 intersphinx_disabled_domains = ['std']
 
-exclude_patterns = [
-        'amaranth/index.rst',
-        'amaranth/cover.rst',
-        'amaranth-soc/index.rst',
-        'amaranth-soc/cover.rst',
-        ]
-
 rediraffe_redirects = {
     "simulator.rst": "amaranth/simulator.rst",
 }
 
-templates_path = ['_templates']
+templates_path = ['chipflow-lib/_templates']
 
 # -- Options for HTML output
 
@@ -69,11 +121,6 @@
 # Favicon is not from `_static`, it gets copied:
 html_favicon = "favicon.png"
 
-# These folders are copied to the documentation's HTML output
-html_static_path = ["_static"]
-
-html_logo = "_static/logo.png"
-
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)
 html_js_files = [
@@ -116,6 +163,7 @@
     r"^https://github\.com/[^/]+/[^/]+/$",
 ]
 
+suppress_warnings = [ "ref.python" ]
 
 # Silence the warnings globally; otherwise they may fire on object destruction and crash completely
 # unrelated tests.

docs/source/index.rst

@@ -1,14 +1,26 @@
-ChipFlow documentation
-======================
+ChipFlow Library Documentation
+==============================
+
+.. image:: chipflow-lib/_assets/chipflow-logo.svg
+   :width: 200px
+   :class: sd-m-auto
+   :name: landing-page-logo
+
+
+ChipFlow IC Design Platform
+---------------------------
+
+ChipFlow is an open-source platform for designing, testing, and manufacturing custom silicon.
+It provides a streamlined workflow from design to fabrication using Python and the Amaranth HDL.
 
-Try our :amaranth:`tutorial-intro-chipflow-platform`.
 
 Contents
 --------
 
 .. toctree::
-   amaranth
-   amaranth-soc
-   chipflow-lib/index.rst
-   tutorial-intro-chipflow-platform
+   :caption: User Guide
+
+   chipflow-lib/index
+   Amaranth Language and Toolchain <amaranth/index>
+   Amaranth System-on-a-Chip toolkit <amaranth-soc/index>
    support