Skip to content

Commit 1407df0

Browse files
robtaylorrobtaylor
committed
Rework documentation
This reworks the documentation to include amaranth, amaranth-soc, and chipflow-lib and struture together well. Updates the CI to have deployments on chipflow-infra.com, with pr reviews. Releases deploy to docs.chipflow.io
1 parent 5c23c13 commit 1407df0

File tree

11 files changed

+930
-383
lines changed

11 files changed

+930
-383
lines changed

‎.github/workflows/build-docs.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Build Docs
2+
on:
3+
workflow_call:
4+
5+
jobs:
6+
build-docs:
7+
runs-on: ubuntu-22.04
8+
9+
env:
10+
GH_TOKEN: "${{ secrets.GITHUB_TOKEN}}"
11+
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
16+
- name: Set up PDM
17+
uses: pdm-project/setup-pdm@v4
18+
with:
19+
python-version: "3.10"
20+
cache: true
21+
22+
- name: Install deps
23+
run: pdm install
24+
25+
- name: Build docs
26+
run: pdm docs
27+
28+
- name: Upload docs artifact
29+
uses: actions/upload-artifact@v4
30+
with:
31+
name: docs
32+
path: docs/build
33+

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Deploy docs internally
2+
on:
3+
push:
4+
branches:
5+
- main
6+
jobs:
7+
build-docs:
8+
uses: ./.github/workflows/build-docs.yml
9+
10+
deploy-internal:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
16+
- name: Download docs artifact
17+
uses: actions/download-artifact@v4
18+
with:
19+
name: docs
20+
path: docs/build
21+
22+
- uses: JamesIves/github-pages-deploy-action@v4
23+
with:
24+
folder: docs/build
25+
branch: gh-pages
26+
clean-exclude: pr-preview
27+
force: false

‎.github/workflows/preview-docs.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# .github/workflows/preview.yml
2+
name: Deploy PR previews
3+
concurrency: preview-${{ github.ref }}
4+
on:
5+
pull_request:
6+
types:
7+
- opened
8+
- reopened
9+
- synchronize
10+
- closed
11+
12+
jobs:
13+
build-docs:
14+
uses: ./.github/workflows/build-docs.yml
15+
16+
deploy-preview:
17+
runs-on: ubuntu-latest
18+
needs: build-docs
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v4
22+
23+
- name: Download docs artifact
24+
uses: actions/download-artifact@v4
25+
with:
26+
name: docs
27+
path: docs/build
28+
29+
- uses: rossjrw/pr-preview-action@v1
30+
with:
31+
source-dir: docs/build
32+
preview-branch: gh-pages
33+
umbrella-dir: pr-preview
34+
action: auto
35+
pages-base-url: chipflow-docs.docs.chipflow-infra.com

‎.github/workflows/main.yml‎ renamed to ‎.github/workflows/release.yml‎

Lines changed: 5 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,10 @@
1-
name: CI
1+
name: Release docs LIVE!
22
on:
3-
push:
4-
branches:
5-
- main
6-
pull_request:
3+
release:
74

85
jobs:
96
build-docs:
10-
runs-on: ubuntu-22.04
11-
steps:
12-
- name: Checkout
13-
uses: actions/checkout@v4
14-
15-
- name: Set up PDM
16-
uses: pdm-project/setup-pdm@v4
17-
with:
18-
python-version: 3.9
19-
20-
- name: Install deps
21-
run: pdm install
22-
23-
- name: Build docs
24-
run: pdm run build
25-
26-
- name: Upload docs artifact
27-
uses: actions/upload-artifact@v4
28-
with:
29-
name: docs
30-
path: docs/build
7+
uses: ./.github/workflows/build-docs.yml
318

329
publish-docs:
3310
needs: build-docs
@@ -36,14 +13,12 @@ jobs:
3613
steps:
3714
- name: Checkout
3815
uses: actions/checkout@v4
39-
with:
40-
fetch-depth: 0
4116

4217
- name: Download docs artifact
4318
uses: actions/download-artifact@v4
4419
with:
4520
name: docs
46-
path: docs/
21+
path: docs/build
4722

4823
- name: Publish "latest" docs
4924
if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
@@ -52,5 +27,5 @@ jobs:
5227
repository-name: chipflow/chipflow.github.io
5328
ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
5429
branch: main
55-
folder: docs/
30+
folder: docs/build
5631
target-folder: en/latest/

‎copy-docs.sh‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
#!/bin/bash
2+
3+
repos=(
4+
'amaranth-lang/amaranth -- -b v0.5.4'
5+
'chipflow/amaranth-soc -- -b reference-docs-chipflow'
6+
'chipflow/chipflow-lib'
7+
)
8+
9+
rm -rf vendor/*
10+
for r in "${repos[@]}"; do
11+
repo=${r%% *}
12+
name=${repo##*/}
13+
if [[ "${r}" =~ "--" ]] ;then
14+
opts="-- ${r##* --}"
15+
else
16+
opts=""
17+
fi
18+
echo "Cloning $repo $opts as vendor/$name"
19+
echo "gh repo clone $repo vendor/$name $opts >/dev/null 2>&1 "
20+
gh repo clone $repo vendor/$name $opts
21+
echo "binding in $repo docs as $name"
22+
rm -rf docs/source/$name
23+
cp -a vendor/$name/docs docs/source/$name
24+
grep -lr ':doc:' docs/source/$name/* | xargs sed -i.bak "s/:doc:/:$name:/g"
25+
done
26+
27+
find docs/source -name "*.bak" -exec rm {} \;
28+

‎docs/source/amaranth-soc.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Amaranth System on Chip toolkit
2+
###############################
3+
4+
.. warning::
5+
6+
This manual is a work in progress and is seriously incomplete!
7+
8+
.. toctree::
9+
:maxdepth: 2
10+
11+
amaranth-soc/memory
12+
amaranth-soc/wishbone
13+
amaranth-soc/csr
14+
amaranth-soc/gpio

‎docs/source/amaranth.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Amaranth Language and Toolchain
2+
###############################
3+
4+
.. warning::
5+
This manual is a work in progress!
6+
7+
.. toctree::
8+
:maxdepth: 2
9+
10+
amaranth/intro
11+
amaranth/install
12+
amaranth/start
13+
amaranth/tutorial
14+
amaranth/guide
15+
amaranth/reference
16+
amaranth/simulator
17+
amaranth/platform
18+
amaranth/stdlib
19+
amaranth/changes
20+
amaranth/contrib

‎docs/source/conf.py‎

Lines changed: 79 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Configuration file for the Sphinx documentation builder.
2-
2+
from pathlib import Path
33
# -- Project information
44

55
project = 'ChipFlow'
@@ -10,23 +10,56 @@
1010
version = '0.1.0'
1111

1212
# -- General configuration
13-
13+
top_dir = Path(__file__).parent / ".." / ".."
1414
extensions = [
1515
'sphinx.ext.duration',
1616
'sphinx.ext.doctest',
17-
'sphinx.ext.autodoc',
18-
'sphinx.ext.autosummary',
1917
'sphinx.ext.intersphinx',
20-
'myst_parser',
18+
'sphinx.ext.autosummary',
2119
'sphinx_copybutton',
20+
'myst_parser',
21+
'sphinx.ext.todo',
22+
'sphinx.ext.autodoc',
23+
'sphinx.ext.napoleon',
24+
'sphinx_rtd_theme',
25+
'sphinxcontrib.platformpicker',
26+
'sphinxcontrib.yowasp_wavedrom',
27+
'sphinx.ext.autodoc',
28+
'sphinxext.rediraffe',
2229
]
30+
"""
31+
"sphinx_design",
32+
"sphinx_design_elements",
33+
"""
34+
35+
rst_prolog = """
36+
.. role:: amaranth
37+
38+
.. role:: amaranth-soc
39+
40+
.. role:: chipflow-lib
41+
42+
.. role:: py(code)
43+
:language: python
44+
"""
45+
2346

2447
intersphinx_mapping = {
2548
'python': ('https://docs.python.org/3/', None),
26-
'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
2749
}
2850
intersphinx_disabled_domains = ['std']
2951

52+
exclude_patterns = [
53+
'amaranth/index.rst',
54+
'amaranth/cover.rst',
55+
'amaranth-soc/index.rst',
56+
'amaranth-soc/cover.rst',
57+
]
58+
59+
rediraffe_redirects = {
60+
"simulator.rst": "amaranth/simulator.rst",
61+
}
62+
3063
templates_path = ['_templates']
3164

3265
# -- Options for HTML output
@@ -36,24 +69,10 @@
3669
# Favicon is not from `_static`, it gets copied:
3770
html_favicon = "favicon.png"
3871

39-
html_theme_options = {
40-
"light_logo": "images/logo.png",
41-
"dark_logo": "images/logo-dark-mode.png",
42-
"analytics_anonymize_ip": True,
43-
"light_css_variables": {
44-
"font-stack": "Poppins, Verdana, sans-serif",
45-
"color-brand-primary": "#7C4FA0",
46-
"color-brand-content": "#7C4FA0",
47-
},
48-
"sidebar_hide_name": True,
49-
}
50-
5172
# These folders are copied to the documentation's HTML output
5273
html_static_path = ["_static"]
5374

54-
html_css_files = [
55-
'css/custom.css',
56-
]
75+
html_logo = "_static/logo.png"
5776

5877
# These paths are either relative to html_static_path
5978
# or fully qualified paths (eg. https://...)
@@ -63,3 +82,42 @@
6382

6483
# -- Options for EPUB output
6584
epub_show_urls = 'footnote'
85+
86+
autodoc_member_order = "bysource"
87+
autodoc_default_options = {
88+
"members": True,
89+
'ignore-module-all': True
90+
}
91+
autodoc_preserve_defaults = True
92+
autodoc_inherit_docstrings = False
93+
94+
napoleon_google_docstring = False
95+
napoleon_numpy_docstring = True
96+
napoleon_use_ivar = True
97+
napoleon_include_init_with_doc = True
98+
napoleon_include_special_with_doc = True
99+
napoleon_custom_sections = [
100+
("Attributes", "params_style"), # by default displays as "Variables", which is confusing
101+
("Members", "params_style"), # `lib.wiring` signature members
102+
"Platform overrides"
103+
]
104+
105+
106+
linkcheck_ignore = [
107+
r"^http://127\.0\.0\.1:8000$",
108+
# Picked up automatically by ReST and doesn't have an index.
109+
r"^https://amaranth-lang\.org/schema/$",
110+
]
111+
112+
linkcheck_anchors_ignore_for_url = [
113+
r"^https://matrix\.to/",
114+
r"^https://web\.libera\.chat/",
115+
# React page with README content included as a JSON payload.
116+
r"^https://github\.com/[^/]+/[^/]+/$",
117+
]
118+
119+
120+
# Silence the warnings globally; otherwise they may fire on object destruction and crash completely
121+
# unrelated tests.
122+
import amaranth._unused
123+
amaranth._unused.MustUse._MustUse__silence = True

‎docs/source/index.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
ChipFlow documentation
22
======================
33

4-
Try our :doc:`tutorial-intro-chipflow-platform`.
4+
Try our :amaranth:`tutorial-intro-chipflow-platform`.
55

66
Contents
77
--------
88

99
.. toctree::
10-
10+
amaranth
11+
amaranth-soc
12+
chipflow-lib/index.rst
1113
tutorial-intro-chipflow-platform
1214
support

0 commit comments

Comments
 (0)