Skip to content

Commit 6f59eec

Browse files
jfngjfng
committed
Set up documentation boilerplate.
1 parent d66881d commit 6f59eec

File tree

8 files changed

+191
-5
lines changed

8 files changed

+191
-5
lines changed

‎.github/workflows/main.yaml

+97-4
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,20 @@ jobs:
1313
matrix:
1414
python-version:
1515
- '3.8'
16+
- '3.9'
17+
- '3.10'
18+
- '3.11'
19+
- '3.12'
20+
- 'pypy-3.8'
21+
- 'pypy-3.9'
22+
- 'pypy-3.10'
1623
# this version range needs to be synchronized with the one in pyproject.toml
1724
amaranth-version:
1825
- 'git'
19-
fail-fast: false
26+
allow-failure:
27+
- false
28+
continue-on-error: '${{ matrix.allow-failure }}'
29+
name: 'test (${{ matrix.python-version }}, HDL ${{ matrix.amaranth-version }})'
2030
steps:
2131
- name: Check out source code
2232
uses: actions/checkout@v3
@@ -45,10 +55,93 @@ jobs:
4555
run:
4656
codecov
4757

48-
required: # group all required workflows into one for the required status check
58+
document:
59+
runs-on: ubuntu-latest
60+
steps:
61+
- name: Check out source code
62+
uses: actions/checkout@v3
63+
with:
64+
fetch-depth: 0
65+
- name: Fetch tags from upstream repository
66+
run: |
67+
git fetch --tags https://github.com/amaranth-lang/amaranth-soc.git
68+
- name: Set up PDM
69+
uses: pdm-project/setup-pdm@v3
70+
with:
71+
python-version: '3.12'
72+
- name: Install dependencies
73+
run: |
74+
pdm install --dev
75+
- name: Build documentation
76+
run: |
77+
pdm run document
78+
- name: Upload documentation archive
79+
uses: actions/upload-artifact@v3
80+
with:
81+
name: docs
82+
path: docs/_build
83+
84+
required: # group all required workflows into one to avoid reconfiguring this in Actions settings
4985
needs:
5086
- test
87+
- document
88+
if: always() && !contains(needs.*.result, 'cancelled')
89+
runs-on: ubuntu-latest
90+
steps:
91+
- run: ${{ contains(needs.*.result, 'failure') && 'false' || 'true' }}
92+
93+
publish-docs:
94+
needs: document
95+
if: github.repository == 'amaranth-lang/amaranth-soc'
96+
runs-on: ubuntu-latest
97+
steps:
98+
- name: Check out source code
99+
uses: actions/checkout@v3
100+
with:
101+
fetch-depth: 0
102+
- name: Download documentation archive
103+
uses: actions/download-artifact@v3
104+
with:
105+
name: docs
106+
path: docs/
107+
- name: Publish development documentation
108+
if: github.event_name == 'push' && github.event.ref == 'refs/heads/main'
109+
uses: JamesIves/github-pages-deploy-action@releases/v4
110+
with:
111+
repository-name: amaranth-lang/amaranth-lang.github.io
112+
ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
113+
branch: main
114+
folder: docs/
115+
target-folder: docs/amaranth-soc/latest/
116+
- name: Publish release documentation
117+
if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
118+
uses: JamesIves/github-pages-deploy-action@releases/v4
119+
with:
120+
repository-name: amaranth-lang/amaranth-lang.github.io
121+
ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
122+
branch: main
123+
folder: docs/
124+
target-folder: docs/amaranth-soc/${{ github.ref_name }}/
125+
126+
publish-docs-dev:
127+
needs: document
128+
if: github.repository != 'amaranth-lang/amaranth-soc'
51129
runs-on: ubuntu-latest
52130
steps:
53-
- run: |
54-
true
131+
- name: Check out source code
132+
uses: actions/checkout@v3
133+
with:
134+
fetch-depth: 0
135+
- name: Download documentation archive
136+
uses: actions/download-artifact@v3
137+
with:
138+
name: docs
139+
path: pages/docs/${{ github.ref_name }}/
140+
- name: Disable Jekyll
141+
run: |
142+
touch pages/.nojekyll
143+
- name: Publish documentation for a branch
144+
uses: JamesIves/github-pages-deploy-action@releases/v4
145+
with:
146+
folder: pages/
147+
clean: false

‎docs/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/

‎docs/_static/custom.css

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
/* Links in text should be underlined. */
2+
a { text-decoration: underline; }
3+
.wy-menu-vertical a, .wy-side-nav-search > a { text-decoration: none; }
4+
5+
/* Match the logo colors in the background. */
6+
.wy-nav-top, .wy-side-nav-search { background-color: #784b9a; }
7+
8+
/* Make the logo more reasonably sized. */
9+
.wy-side-nav-search > a img.logo { width: 160px; }
10+
11+
/* Some of our section titles are looong */
12+
@media screen and (min-width:769px) {
13+
.wy-nav-side, .wy-side-scroll, .wy-menu-vertical { width: 340px; }
14+
.wy-side-nav-search { width: 325px; }
15+
.wy-nav-content-wrap { margin-left: 340px; }
16+
}
17+
18+
/* We don't have a version picker widget */
19+
.wy-nav-side { padding-bottom: 0; }
20+
21+
/* Many of our diagnostics are even longer */
22+
.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre { white-space: pre-wrap; }

‎docs/_static/logo.png

287 KB
Loading

‎docs/conf.py

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
import os, sys
2+
sys.path.insert(0, os.path.abspath("."))
3+
4+
import time
5+
import amaranth_soc
6+
7+
project = "System on Chip toolkit for Amaranth HDL"
8+
version = amaranth_soc.__version__.replace(".editable", "")
9+
release = version.split("+")[0]
10+
copyright = time.strftime("2020—%Y, Amaranth project contributors")
11+
12+
extensions = [
13+
"sphinx.ext.intersphinx",
14+
"sphinx.ext.doctest",
15+
"sphinx.ext.todo",
16+
"sphinx.ext.autodoc",
17+
"sphinx.ext.napoleon",
18+
"sphinx_rtd_theme",
19+
]
20+
21+
with open(".gitignore") as f:
22+
exclude_patterns = [line.strip() for line in f.readlines()]
23+
24+
root_doc = "cover"
25+
26+
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
27+
28+
todo_include_todos = True
29+
30+
autodoc_member_order = "bysource"
31+
autodoc_default_options = {
32+
"members": True
33+
}
34+
autodoc_preserve_defaults = True
35+
36+
napoleon_google_docstring = False
37+
napoleon_numpy_docstring = True
38+
napoleon_use_ivar = True
39+
napoleon_include_init_with_doc = True
40+
napoleon_include_special_with_doc = True
41+
42+
html_theme = "sphinx_rtd_theme"
43+
html_static_path = ["_static"]
44+
html_css_files = ["custom.css"]
45+
html_logo = "_static/logo.png"
46+
47+
rst_prolog = """
48+
.. role:: pc(code)
49+
:language: python
50+
"""

‎docs/cover.rst

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. This page is loaded if you click on the Amaranth logo.
2+
3+
Amaranth project documentation
4+
##############################
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
9+
Language & toolchain <https://amaranth-lang.org/docs/amaranth/latest/>
10+
Standard I/O components <https://amaranth-lang.org/docs/amaranth-stdio/latest/>
11+
index

‎docs/index.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
System on Chip toolkit
2+
######################
3+
4+
.. warning::
5+
6+
This manual is a work in progress and is seriously incomplete!

‎pyproject.toml

+4-1
Original file line numberDiff line numberDiff line change
@@ -48,4 +48,7 @@ test-code.cmd = "python -m coverage run -m unittest discover -t . -s tests -v"
4848
test-docs.cmd = "sphinx-build -b doctest docs docs/_build"
4949

5050
document.cmd = "sphinx-build docs docs/_build"
51-
document-live.cmd = "sphinx-autobuild docs docs/_build --watch amaranth"
51+
document-live.cmd = "sphinx-autobuild docs docs/_build --watch amaranth_soc"
52+
53+
coverage-text.cmd = "python -m coverage report"
54+
coverage-html.cmd = "python -m coverage html"

0 commit comments

Comments
 (0)