Fix sphinx warnings

Author: robtaylor

docs/source/amaranth-soc.rst

@@ -2,6 +2,7 @@
 import os
 import sys
 from pathlib import Path
+from itertools import starmap
 
 top_path = Path('../../')
 sys.path.append(str((top_path / 'tools').absolute()))
@@ -15,6 +16,13 @@
     ('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'
@@ -75,7 +83,7 @@
         top_path / "vendor/chipflow-lib/chipflow_lib",
         ]
 autoapi_generate_api_docs = True
-autoapi_template_dir = "_templates/autoapi"
+autoapi_template_dir = "chipflow-lib/_templates/autoapi"
 # autoapi_verbose_visibility = 2
 autoapi_keep_files = True
 autoapi_options = [
@@ -84,11 +92,14 @@
     'show-module-summary',
     'imported-members',
 ]
+autoapi_root = "chipflow-lib/autoapi"
 
 # Exclude autoapi templates and in-progress stuff
 exclude_patterns = [
     autoapi_template_dir,
-    "unfinished",
+    "chipflow-lib/unfinished",
+    "amaranth/cover.rst",
+    "amaranth-soc/cover.rst",
 ]
 
 
@@ -97,18 +108,11 @@
 }
 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
 
@@ -159,12 +163,9 @@
     r"^https://github\.com/[^/]+/[^/]+/$",
 ]
 
+suppress_warnings = [ "ref.python" ]
 
 # 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
-
-# copy in the doc sources from our repos
-
-copy_docs(repos)

docs/source/amaranth.rst

@@ -1,7 +1,7 @@
 ChipFlow Library Documentation
 ==============================
 
-.. image:: _assets/chipflow-logo.svg
+.. image:: chipflow-lib/_assets/chipflow-logo.svg
    :width: 200px
    :class: sd-m-auto
    :name: landing-page-logo
@@ -13,16 +13,14 @@ 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.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: User Guide
-
 
 Contents
 --------
 
 .. toctree::
-   chipflow-lib
-   amaranth
-   amaranth-soc
+   :caption: User Guide
+
+   chipflow-lib/index
+   Amaranth Language and Toolchain <amaranth/index>
+   Amaranth System-on-a-Chip toolkit <amaranth-soc/index>
    support

docs/source/conf.py

@@ -22,18 +22,13 @@ dependencies = [
   "sphinx_design_elements @ git+https://github.com/panodata/sphinx-design-elements@linktree",
   "sphinxext-rediraffe>=0.2.7",
   "sphinx-autoapi>=3.6.0",
+  "jschon>=0.11.1",
 ]
 
 [build-system]
 requires = ["pdm-backend"]
 build-backend = "pdm.backend"
 
-[dependency-groups]
-dev = [
-    "-e amaranth@file:///${PROJECT_ROOT}/vendor/amaranth",
-    "-e amaranth_soc@file:///${PROJECT_ROOT}/vendor/amaranth-soc",
-]
-
 [tool.pdm.scripts]
 docs.cmd= "sphinx-build docs/source/ docs/build/"
 autodocs.cmd= "sphinx-autobuild docs/source/ docs/build/"

docs/source/index.rst

@@ -10,12 +10,27 @@
 from pathlib import Path
 from typing import List, Tuple
 
-def copy_docs(repos: List[Tuple[str, str]]):
+def copy_docs(repos: List[Tuple[str, str]]) -> List[Path]:
+    """"
+    Pull in docs from other repos.
+
+    Clones the repos at the given refs in $PDM_PROJECT_ROOT/vendor
+    Then copies the doc dirs into this one, tranforming `:role:` references appropriatly
+
+    Args:
+        repos: List of tuples containing git repo and ref
+
+    Returns:
+        A list of the repo locations
+    """
+
     # Ensure vendor directory exists
     root_path = Path(os.environ['PDM_PROJECT_ROOT'])
     vendor = root_path / 'vendor'
     vendor.mkdir(exist_ok=True)
 
+    repo_list = []
+
     for repo_info in repos:
         repo_path = Path(repo_info[0])
         ref = repo_info[1]
@@ -40,6 +55,8 @@ def copy_docs(repos: List[Tuple[str, str]]):
             # Checkout ref
             subprocess.run(['git', '-C', repodir, 'checkout', '-f', '--detach', ref], check=True)
 
+        repo_list.append(repodir)
+
         print(f"Binding in {repo_path} docs as {name}")
 
         if docs_dest_path.exists():
@@ -66,3 +83,5 @@ def copy_docs(repos: List[Tuple[str, str]]):
 
     # assemble a
     print("Documentation copy completed successfully")
+
+    return repo_list