diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 9f30979..cc7b1e5 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -14,11 +14,21 @@ jobs:
matrix:
python-version:
- '3.8'
+ - '3.9'
+ - '3.10'
+ - '3.11'
+ - '3.12'
+ - 'pypy-3.8'
+ - 'pypy-3.9'
+ - 'pypy-3.10'
# this version range needs to be synchronized with the one in pyproject.toml
amaranth-version:
- '0.4'
- 'git'
- fail-fast: false
+ allow-failure:
+ - false
+ continue-on-error: '${{ matrix.allow-failure }}'
+ name: 'test (${{ matrix.python-version }}, HDL ${{ matrix.amaranth-version }})'
steps:
- name: Check out source code
uses: actions/checkout@v3
@@ -47,10 +57,92 @@ jobs:
run:
codecov
- required: # group all required workflows into one for the required status check
+ document:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Check out source code
+ uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
+ - name: Fetch tags from upstream repository
+ run: |
+ git fetch --tags https://github.com/amaranth-lang/amaranth-stdio.git
+ - name: Set up PDM
+ uses: pdm-project/setup-pdm@v3
+ with:
+ python-version: '3.12'
+ - name: Install dependencies
+ run: |
+ pdm install --dev
+ - name: Build documentation
+ run: |
+ pdm run document
+ - name: Upload documentation archive
+ uses: actions/upload-artifact@v3
+ with:
+ name: docs
+ path: docs/_build
+
+ required: # group all required workflows into one to avoid reconfiguring this in Actions settings
needs:
- test
+ if: always() && !contains(needs.*.result, 'cancelled')
+ runs-on: ubuntu-latest
+ steps:
+ - run: ${{ contains(needs.*.result, 'failure') && 'false' || 'true' }}
+
+ publish-docs:
+ needs: document
+ if: github.repository == 'amaranth-lang/amaranth-stdio'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Check out source code
+ uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
+ - name: Download documentation archive
+ uses: actions/download-artifact@v3
+ with:
+ name: docs
+ path: docs/
+ - name: Publish development documentation
+ if: github.event_name == 'push' && github.event.ref == 'refs/heads/main'
+ uses: JamesIves/github-pages-deploy-action@releases/v4
+ with:
+ repository-name: amaranth-lang/amaranth-lang.github.io
+ ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
+ branch: main
+ folder: docs/
+ target-folder: docs/amaranth-stdio/latest/
+ - name: Publish release documentation
+ if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
+ uses: JamesIves/github-pages-deploy-action@releases/v4
+ with:
+ repository-name: amaranth-lang/amaranth-lang.github.io
+ ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
+ branch: main
+ folder: docs/
+ target-folder: docs/amaranth-stdio/${{ github.ref_name }}/
+
+ publish-docs-dev:
+ needs: document
+ if: github.repository != 'amaranth-lang/amaranth-stdio'
runs-on: ubuntu-latest
steps:
- - run: |
- true
+ - name: Check out source code
+ uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
+ - name: Download documentation archive
+ uses: actions/download-artifact@v3
+ with:
+ name: docs
+ path: pages/docs/${{ github.ref_name }}/
+ - name: Disable Jekyll
+ run: |
+ touch pages/.nojekyll
+ - name: Publish documentation for a branch
+ uses: JamesIves/github-pages-deploy-action@releases/v4
+ with:
+ folder: pages/
+ clean: false
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..69fa449
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+_build/
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
new file mode 100644
index 0000000..163b9fa
--- /dev/null
+++ b/docs/_static/custom.css
@@ -0,0 +1,10 @@
+/* Some of our section titles are looong */
+.wy-nav-side, .wy-side-scroll, .wy-menu-vertical { width: 340px; }
+.wy-side-nav-search { width: 325px; }
+.wy-nav-content-wrap { margin-left: 340px; }
+
+/* We don't have a version picker widget */
+.wy-nav-side { padding-bottom: 0; }
+
+/* Many of our diagnostics are even longer */
+.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre { white-space: pre-wrap; }
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
new file mode 100644
index 0000000..cb2e7cf
Binary files /dev/null and b/docs/_static/logo.png differ
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..cf23582
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,50 @@
+import os, sys
+sys.path.insert(0, os.path.abspath("."))
+
+import time
+import amaranth_stdio
+
+project = "Amaranth standard I/O components"
+version = amaranth_stdio.__version__.replace(".editable", "")
+release = version.split("+")[0]
+copyright = time.strftime("2020—%Y, Amaranth project contributors")
+
+extensions = [
+ "sphinx.ext.intersphinx",
+ "sphinx.ext.doctest",
+ "sphinx.ext.todo",
+ "sphinx.ext.autodoc",
+ "sphinx.ext.napoleon",
+ "sphinx_rtd_theme",
+]
+
+with open(".gitignore") as f:
+ exclude_patterns = [line.strip() for line in f.readlines()]
+
+root_doc = "cover"
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+todo_include_todos = True
+
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+ "members": True
+}
+autodoc_preserve_defaults = True
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_ivar = True
+napoleon_include_init_with_doc = True
+napoleon_include_special_with_doc = True
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_logo = "_static/logo.png"
+
+rst_prolog = """
+.. role:: pc(code)
+ :language: python
+"""
diff --git a/docs/cover.rst b/docs/cover.rst
new file mode 100644
index 0000000..820c390
--- /dev/null
+++ b/docs/cover.rst
@@ -0,0 +1,11 @@
+.. This page is loaded if you click on the Amaranth logo.
+
+Amaranth project documentation
+##############################
+
+.. toctree::
+ :maxdepth: 1
+
+ Language & toolchain
+ index
+ System on Chip toolkit
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..7854d18
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,6 @@
+Standard I/O components
+#######################
+
+.. warning::
+
+ This manual is a work in progress and is seriously incomplete!
diff --git a/pyproject.toml b/pyproject.toml
index 3ad7436..eb54ba9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -48,4 +48,7 @@ test-code.cmd = "python -m coverage run -m unittest discover -t . -s tests -v"
test-docs.cmd = "sphinx-build -b doctest docs/ docs/_build"
document.cmd = "sphinx-build docs/ docs/_build/"
-document-live.cmd = "sphinx-autobuild docs/ docs/_build/ --watch amaranth"
+document-live.cmd = "sphinx-autobuild docs/ docs/_build/ --watch amaranth_stdio"
+
+coverage-text.cmd = "python -m coverage report"
+coverage-html.cmd = "python -m coverage html"