Skip to content

Commit cf7c4c0

Browse files
whitequarkwhitequark
committed
Set up documentation boilerplate.
1 parent 0468ce0 commit cf7c4c0

File tree

8 files changed

+179
-5
lines changed

8 files changed

+179
-5
lines changed

‎.github/workflows/main.yml‎

Lines changed: 97 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,21 @@ jobs:
1414
matrix:
1515
python-version:
1616
- '3.8'
17+
- '3.9'
18+
- '3.10'
19+
- '3.11'
20+
- '3.12'
21+
- 'pypy-3.8'
22+
- 'pypy-3.9'
23+
- 'pypy-3.10'
1724
# this version range needs to be synchronized with the one in pyproject.toml
1825
amaranth-version:
1926
- '0.4'
2027
- 'git'
21-
fail-fast: false
28+
allow-failure:
29+
- false
30+
continue-on-error: '${{ matrix.allow-failure }}'
31+
name: 'test (${{ matrix.python-version }}, HDL ${{ matrix.amaranth-version }})'
2232
steps:
2333
- name: Check out source code
2434
uses: actions/checkout@v3
@@ -47,10 +57,93 @@ jobs:
4757
run:
4858
codecov
4959

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

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/

‎docs/_static/custom.css‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/* Some of our section titles are looong */
2+
.wy-nav-side, .wy-side-scroll, .wy-menu-vertical { width: 340px; }
3+
.wy-side-nav-search { width: 325px; }
4+
.wy-nav-content-wrap { margin-left: 340px; }
5+
6+
/* We don't have a version picker widget */
7+
.wy-nav-side { padding-bottom: 0; }
8+
9+
/* Many of our diagnostics are even longer */
10+
.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‎

Lines changed: 50 additions & 0 deletions
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_stdio
6+
7+
project = "Amaranth standard I/O components"
8+
version = amaranth_stdio.__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‎

Lines changed: 11 additions & 0 deletions
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+
index
11+
System on Chip toolkit <https://amaranth-lang.org/docs/amaranth-soc/latest/>

‎docs/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Standard I/O components
2+
#######################
3+
4+
.. warning::
5+
6+
This manual is a work in progress and is seriously incomplete!

‎pyproject.toml‎

Lines changed: 4 additions & 1 deletion
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_stdio"
52+
53+
coverage-text.cmd = "python -m coverage report"
54+
coverage-html.cmd = "python -m coverage html"

0 commit comments

Comments
 (0)