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"