Set up documentation boilerplate.

.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,93 @@ 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
+      - document
+    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

docs/.gitignore

@@ -0,0 +1 @@
+_build/

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; }

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
+"""

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 <https://amaranth-lang.org/docs/amaranth/latest/>
+   index
+   System on Chip toolkit <https://amaranth-lang.org/docs/amaranth-soc/latest/>

docs/index.rst

@@ -0,0 +1,6 @@
+Standard I/O components
+#######################
+
+.. warning::
+
+   This manual is a work in progress and is seriously incomplete!

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"