Rework documentation

.github/workflows/build-docs.yml

@@ -0,0 +1,33 @@
+name: Build Docs
+on:
+  workflow_call:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-22.04
+
+    env:
+      GH_TOKEN: "${{ secrets.GITHUB_TOKEN}}"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: "3.10"
+          cache: true
+
+      - name: Install deps
+        run: pdm install
+
+      - name: Build docs
+        run: pdm docs
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/build
+

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

@@ -0,0 +1,27 @@
+name: Deploy docs internally
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build-docs:
+    uses: ./.github/workflows/build-docs.yml
+
+  deploy-internal:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: docs/build
+
+      - uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/build
+          branch: gh-pages
+          clean-exclude: pr-preview
+          force: false

.github/workflows/preview-docs.yml

@@ -0,0 +1,35 @@
+# .github/workflows/preview.yml
+name: Deploy PR previews
+concurrency: preview-${{ github.ref }}
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+
+jobs:
+  build-docs:
+    uses: ./.github/workflows/build-docs.yml
+
+  deploy-preview:
+    runs-on: ubuntu-latest
+    needs: build-docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: docs/build
+
+      - uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: docs/build
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+          action: auto
+          pages-base-url: chipflow-docs.docs.chipflow-infra.com

.github/workflows/main.yml → .github/workflows/release.yml

@@ -1,33 +1,10 @@
-name: CI
+name: Release docs LIVE!
 on:
-  push:
-    branches:
-    - main
-  pull_request:
+  release:
 
 jobs:
   build-docs:
-    runs-on: ubuntu-22.04
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up PDM
-        uses: pdm-project/setup-pdm@v4
-        with:
-          python-version: 3.9
-
-      - name: Install deps
-        run: pdm install
-
-      - name: Build docs
-        run: pdm run build
-
-      - name: Upload docs artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: docs
-          path: docs/build
+    uses: ./.github/workflows/build-docs.yml
 
   publish-docs:
     needs: build-docs
@@ -36,14 +13,12 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
       - name: Download docs artifact
         uses: actions/download-artifact@v4
         with:
           name: docs
-          path: docs/
+          path: docs/build
 
       - name: Publish "latest" docs
         if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
@@ -52,5 +27,5 @@ jobs:
           repository-name: chipflow/chipflow.github.io
           ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
           branch: main
-          folder: docs/
+          folder: docs/build
           target-folder: en/latest/

copy-docs.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+repos=(
+'amaranth-lang/amaranth -- -b v0.5.4'
+'chipflow/amaranth-soc -- -b reference-docs-chipflow'
+'chipflow/chipflow-lib'
+)
+
+rm -rf vendor/*
+for r in "${repos[@]}"; do
+  repo=${r%% *} 
+  name=${repo##*/} 
+  if [[ "${r}" =~ "--" ]] ;then
+    opts="-- ${r##* --}"
+  else 
+    opts="" 
+  fi
+  echo "Cloning $repo $opts as vendor/$name"
+  echo "gh repo clone $repo vendor/$name $opts >/dev/null 2>&1 "
+  gh repo clone $repo vendor/$name $opts
+  echo "binding in $repo docs as $name"
+  rm -rf docs/source/$name
+  cp -a  vendor/$name/docs docs/source/$name
+  grep -lr ':doc:' docs/source/$name/* |  xargs sed -i.bak "s/:doc:/:$name:/g"
+done
+
+find docs/source -name "*.bak" -exec rm {} \;
+

docs/source/amaranth-soc.rst

@@ -0,0 +1,14 @@
+Amaranth System on Chip toolkit
+###############################
+
+.. warning::
+
+   This manual is a work in progress and is seriously incomplete!
+
+.. toctree::
+   :maxdepth: 2
+
+   amaranth-soc/memory
+   amaranth-soc/wishbone
+   amaranth-soc/csr
+   amaranth-soc/gpio

docs/source/amaranth.rst

@@ -0,0 +1,20 @@
+Amaranth Language and Toolchain
+###############################
+
+.. warning::
+   This manual is a work in progress!
+
+.. toctree::
+   :maxdepth: 2
+
+   amaranth/intro
+   amaranth/install
+   amaranth/start
+   amaranth/tutorial
+   amaranth/guide
+   amaranth/reference
+   amaranth/simulator
+   amaranth/platform
+   amaranth/stdlib
+   amaranth/changes
+   amaranth/contrib

docs/source/conf.py

@@ -1,5 +1,5 @@
 # Configuration file for the Sphinx documentation builder.
-
+from pathlib import Path
 # -- Project information
 
 project = 'ChipFlow'
@@ -10,23 +10,56 @@
 version = '0.1.0'
 
 # -- General configuration
-
+top_dir = Path(__file__).parent / ".." / ".."
 extensions = [
     'sphinx.ext.duration',
     'sphinx.ext.doctest',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
-    'myst_parser',
+    'sphinx.ext.autosummary',
     'sphinx_copybutton',
+    'myst_parser',
+    'sphinx.ext.todo',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme',
+    'sphinxcontrib.platformpicker',
+    'sphinxcontrib.yowasp_wavedrom',
+    'sphinx.ext.autodoc',
+    'sphinxext.rediraffe',
 ]
+"""
+    "sphinx_design",
+    "sphinx_design_elements",
+"""
+
+rst_prolog = """
+.. role:: amaranth
+
+.. role:: amaranth-soc
+
+.. role:: chipflow-lib
+
+.. role:: py(code)
+   :language: python
+"""
+
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', 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']
 
 # -- Options for HTML output
@@ -36,24 +69,10 @@
 # Favicon is not from `_static`, it gets copied:
 html_favicon = "favicon.png"
 
-html_theme_options = {
-    "light_logo": "images/logo.png",
-    "dark_logo": "images/logo-dark-mode.png",
-    "analytics_anonymize_ip": True,
-    "light_css_variables": {
-        "font-stack": "Poppins, Verdana, sans-serif",
-        "color-brand-primary": "#7C4FA0",
-        "color-brand-content": "#7C4FA0",
-    },
-    "sidebar_hide_name": True,
-}
-
 # These folders are copied to the documentation's HTML output
 html_static_path = ["_static"]
 
-html_css_files = [
-    'css/custom.css',
-]
+html_logo = "_static/logo.png"
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)
@@ -63,3 +82,42 @@
 
 # -- Options for EPUB output
 epub_show_urls = 'footnote'
+
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    'ignore-module-all': True
+}
+autodoc_preserve_defaults = True
+autodoc_inherit_docstrings = False
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_ivar = True
+napoleon_include_init_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_custom_sections = [
+    ("Attributes", "params_style"), # by default displays as "Variables", which is confusing
+    ("Members", "params_style"), # `lib.wiring` signature members
+    "Platform overrides"
+]
+
+
+linkcheck_ignore = [
+    r"^http://127\.0\.0\.1:8000$",
+    # Picked up automatically by ReST and doesn't have an index.
+    r"^https://amaranth-lang\.org/schema/$",
+]
+
+linkcheck_anchors_ignore_for_url = [
+    r"^https://matrix\.to/",
+    r"^https://web\.libera\.chat/",
+    # React page with README content included as a JSON payload.
+    r"^https://github\.com/[^/]+/[^/]+/$",
+]
+
+
+# Silence the warnings globally; otherwise they may fire on object destruction and crash completely
+# unrelated tests.
+import amaranth._unused
+amaranth._unused.MustUse._MustUse__silence = True

docs/source/index.rst

@@ -1,12 +1,14 @@
 ChipFlow documentation
 ======================
 
-Try our :doc:`tutorial-intro-chipflow-platform`.
+Try our :amaranth:`tutorial-intro-chipflow-platform`.
 
 Contents
 --------
 
 .. toctree::
-
+   amaranth
+   amaranth-soc
+   chipflow-lib/index.rst
    tutorial-intro-chipflow-platform
    support