swiftdoc 0.6.1__tar.gz

swiftdoc-0.6.1/.gitattributes

@@ -0,0 +1,3 @@
+# Shell scripts must keep LF endings, even in a Windows checkout
+# (core.autocrlf), or sh/bash fail on the carriage returns.
+*.sh text eol=lf

swiftdoc-0.6.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,83 @@
+name: Bug report
+description: Something is wrong with swiftdoc or the site it generates.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. The smallest Python file that shows the problem is the most useful thing you can include.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you see, and what did you expect instead?
+      placeholder: |
+        The method `Engine.run` is missing from the generated page.
+        I expected it to be listed under the `Engine` class.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: The command you ran and a minimal Python file (or a public repository) that triggers the problem.
+      placeholder: |
+        swiftdoc --src ./src --out ./docs --name myproject
+
+        ```python
+        class Engine:
+            def run(self) -> None:
+                """Start the engine."""
+        ```
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Where is the problem?
+      options:
+        - Parsing (missing or wrong classes, functions, signatures)
+        - Docstring rendering (Markdown, macros, code highlighting)
+        - Generated site (layout, theme, search, navigation)
+        - Command line, configuration or setup wizard
+        - Installation or release binaries
+        - Something else
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: swiftdoc version
+      description: Output of `swiftdoc --version`.
+      placeholder: swiftdoc 0.6.1
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - macOS
+        - Windows
+    validations:
+      required: true
+
+  - type: input
+    id: browser
+    attributes:
+      label: Browser
+      description: Only for problems with the generated site.
+      placeholder: Firefox 140, Safari 19, ...
+
+  - type: textarea
+    id: output
+    attributes:
+      label: Terminal output
+      description: Any errors or warnings swiftdoc printed. This is shown as code, so no backticks are needed.
+      render: text

swiftdoc-0.6.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Usage and options
+    url: https://github.com/kura120/swiftdoc#usage
+    about: Flags, macros, custom templates and troubleshooting are covered in the README.

swiftdoc-0.6.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,47 @@
+name: Feature request
+description: Suggest a new feature or an improvement.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please check the [open issues](https://github.com/kura120/swiftdoc/issues) and the [roadmap](https://github.com/kura120/swiftdoc/issues/3) first, in case it is already planned.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do, and what gets in the way today?
+      placeholder: My project uses Google-style docstrings, and `Args:` sections show up as plain text.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: What should swiftdoc do? Example input and output help a lot.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Parsing and docstrings
+        - Templates and theme
+        - Command line and configuration
+        - Output formats
+        - Performance
+        - Installation and CI integration
+        - Documentation
+        - Something else
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives
+      description: Workarounds you use today, or how other tools (pdoc, Sphinx, ...) handle this.

swiftdoc-0.6.1/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- What does this change, and why? -->
+
+Closes #
+
+## Changes
+
+-
+
+## Test plan
+
+- [ ] `cargo fmt --check`
+- [ ] `cargo clippy --locked --all-targets -- -D warnings`
+- [ ] `cargo test`
+- [ ] Generated a site for a real project and checked the result
+- [ ] Parser or renderer change: release-build timing on a large package compared with `master`
+- [ ] Theme change: checked light and dark, and phone and desktop widths (screenshots below)
+- [ ] README updated for new flags, configuration or macros
+
+## Screenshots
+
+<!-- For theme or layout changes. Delete otherwise. -->

swiftdoc-0.6.1/.github/workflows/action-test.yaml

@@ -0,0 +1,138 @@
+name: Action self-test
+
+# Exercises action.yml on each runner OS. "release" downloads the latest
+# published binary (the download, checksum and extract path); "source" builds
+# this commit with cargo, so changes to swiftdoc itself are covered too.
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - action.yml
+      - scripts/action/**
+      - scripts/pre-commit.sh
+      - .pre-commit-hooks.yaml
+      - .github/workflows/action-test.yaml
+  pull_request:
+    paths:
+      - action.yml
+      - scripts/action/**
+      - scripts/pre-commit.sh
+      - .pre-commit-hooks.yaml
+      - .github/workflows/action-test.yaml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  action:
+    name: Action (${{ matrix.os }}, ${{ matrix.install }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # "release" joins once v0.6.1, the first complete swiftdoc release, is published.
+        install: [source]
+        include:
+          - os: ubuntu-24.04-arm
+            install: source
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        if: matrix.install == 'source'
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Run the action
+        id: swiftdoc
+        uses: ./
+        with:
+          install: ${{ matrix.install }}
+          src: tests/fixtures/sample
+          out: _site-test
+          name: sample
+          args: --strict --theme dark --doc-version "1.2.3 beta"
+
+      - name: Check the output
+        shell: bash
+        env:
+          OUT: ${{ steps.swiftdoc.outputs.out }}
+          VERSION: ${{ steps.swiftdoc.outputs.version }}
+        run: |
+          set -x
+          test "$OUT" = "_site-test"
+          test -n "$VERSION"
+          test -f _site-test/index.html
+          test -f _site-test/guide.html
+          test -f _site-test/search-index.js
+          grep -q "1.2.3 beta" _site-test/index.html
+
+  pinned:
+    # Runs once v0.6.1, the first complete swiftdoc release, is published.
+    if: false
+    name: Action (ubuntu-latest, pinned version)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run the action
+        id: swiftdoc
+        uses: ./
+        with:
+          version: "0.6.1"
+          src: tests/fixtures/sample
+          out: _site-test
+          name: sample
+
+      - name: Check the output
+        shell: bash
+        env:
+          VERSION: ${{ steps.swiftdoc.outputs.version }}
+        run: |
+          set -x
+          test "$VERSION" = "0.6.1"
+          test -f _site-test/index.html
+
+  pre-commit:
+    name: pre-commit hook
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Builds from source until v0.6.1, the first complete swiftdoc release, is published.
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Install swiftdoc
+        uses: ./
+        with:
+          install: source
+          src: tests/fixtures/sample
+          out: _site-test
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Try the hook against a scratch repository
+        shell: bash
+        run: |
+          set -x
+          pip install pre-commit
+          hook_repo="$PWD"
+          work="$RUNNER_TEMP/consumer"
+          mkdir -p "$work/pkg"
+          cd "$work"
+          git init -q .
+          printf '"""Package.\n\n#sd-doc-link: pkg.engine.Engine\n"""\n' > pkg/__init__.py
+          printf '"""Engine module."""\n\n\nclass Engine:\n    """Runs things."""\n' > pkg/engine.py
+          git add -A
+          pre-commit try-repo "$hook_repo" swiftdoc --all-files
+          # A broken doc-link must fail the hook.
+          sed -i 's/pkg.engine.Engine/pkg.engine.Missing/' pkg/__init__.py
+          git add -A
+          if pre-commit try-repo "$hook_repo" swiftdoc --all-files; then
+            echo "hook passed on a broken doc-link"
+            exit 1
+          fi

swiftdoc-0.6.1/.github/workflows/ci.yaml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lint:
+    name: Format and Clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Check formatting
+        run: cargo fmt --check
+      - name: Clippy
+        run: cargo clippy --locked --all-targets -- -D warnings
+
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Build
+        run: cargo build --locked
+      - name: Test
+        run: cargo test --locked
+
+  a11y:
+    name: Accessibility (axe-core, keyboard)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: tests/a11y/package-lock.json
+      - name: Generate the fixture sites
+        # An empty --config keeps the repository's own pyproject.toml out.
+        run: |
+          cargo build --locked
+          ./target/debug/swiftdoc --config /dev/null --src tests/fixtures/sample --out "$RUNNER_TEMP/sample-site" --name demo
+          ./target/debug/swiftdoc --config /dev/null --src tests/fixtures/variables --out "$RUNNER_TEMP/variables-site" --name variables
+          ./target/debug/swiftdoc --config /dev/null --src tests/fixtures/nested --out "$RUNNER_TEMP/nested-site" --name nested
+          ./target/debug/swiftdoc --config /dev/null --src tests/fixtures/docstrings --out "$RUNNER_TEMP/docstrings-site" --name docstrings
+      - name: Install axe-core and Playwright
+        working-directory: tests/a11y
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium
+      - name: axe-core, WCAG 2.2 AA (3 layouts x light and dark)
+        working-directory: tests/a11y
+        run: node audit.js "$RUNNER_TEMP/sample-site" "$RUNNER_TEMP/variables-site" "$RUNNER_TEMP/nested-site" "$RUNNER_TEMP/docstrings-site" --quick
+      - name: Keyboard
+        working-directory: tests/a11y
+        run: node keyboard.js "$RUNNER_TEMP/sample-site"
+      - name: Landmarks and headings
+        working-directory: tests/a11y
+        run: node structure.js "$RUNNER_TEMP/sample-site" "$RUNNER_TEMP/variables-site" "$RUNNER_TEMP/nested-site" "$RUNNER_TEMP/docstrings-site"

swiftdoc-0.6.1/.github/workflows/packaging.yaml

@@ -0,0 +1,53 @@
+name: Packaging
+
+# Builds the swiftdoc wheel and sdist the way release.yaml does, installs the
+# wheel and runs it, so packaging changes are tested before a release.
+
+on:
+  pull_request:
+    paths:
+      - pyproject.toml
+      - Cargo.toml
+      - Cargo.lock
+      - README.md
+      - scripts/wheel-smoke-test.sh
+      - .github/workflows/packaging.yaml
+      - .github/workflows/release.yaml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  wheel:
+    name: Build and test wheel (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: x86_64-unknown-linux-gnu
+          manylinux: auto
+          args: --release --locked --out dist
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Check metadata
+        run: |
+          python -m pip install twine
+          python -m twine check --strict dist/*
+
+      - name: Install the wheel and run it
+        run: |
+          python -m pip install --no-index --find-links dist swiftdoc
+          sh scripts/wheel-smoke-test.sh

swiftdoc-0.6.1/.github/workflows/release.yaml

@@ -0,0 +1,265 @@
+name: Release Binaries
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: Build and Upload (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            artifact_name: swiftdoc
+            asset_name: swiftdoc-x86_64-unknown-linux-gnu.tar.gz
+          - os: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            artifact_name: swiftdoc
+            asset_name: swiftdoc-aarch64-unknown-linux-gnu.tar.gz
+          - os: macos-latest
+            target: x86_64-apple-darwin
+            artifact_name: swiftdoc
+            asset_name: swiftdoc-x86_64-apple-darwin.tar.gz
+          - os: macos-latest
+            target: aarch64-apple-darwin
+            artifact_name: swiftdoc
+            asset_name: swiftdoc-aarch64-apple-darwin.tar.gz
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            artifact_name: swiftdoc.exe
+            asset_name: swiftdoc-x86_64-pc-windows-msvc.zip
+
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v4
+
+      - name: Install Rust Toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Check tag matches Cargo.toml version
+        shell: bash
+        run: |
+          version=$(grep -m1 '^version' Cargo.toml | sed -E 's/.*"([^"]+)".*/\1/')
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match Cargo.toml version $version"
+            exit 1
+          fi
+
+      # Release binaries are not UPX-packed: the archives are already
+      # compressed, and packed executables are unsupported on macOS and
+      # frequently flagged by antivirus tools on Windows.
+      - name: Build Binary (Unix)
+        if: matrix.os != 'windows-latest'
+        run: |
+          chmod +x ./scripts/build.sh
+          ./scripts/build.sh ${{ matrix.target }}
+
+      - name: Build Binary (Windows)
+        if: matrix.os == 'windows-latest'
+        run: pwsh -File ./scripts/build.ps1 -Target ${{ matrix.target }}
+
+      - name: Archive Binary (Unix)
+        if: matrix.os != 'windows-latest'
+        run: |
+          tar -czf ${{ matrix.asset_name }} -C target/${{ matrix.target }}/release ${{ matrix.artifact_name }}
+
+      - name: Archive Binary (Windows)
+        if: matrix.os == 'windows-latest'
+        shell: pwsh
+        run: |
+          Compress-Archive -Path target\${{ matrix.target }}\release\${{ matrix.artifact_name }} -DestinationPath ${{ matrix.asset_name }}
+
+      # "<hash>  <file>", the format sha256sum/shasum -c and the installers read.
+      - name: Write SHA-256 checksum
+        shell: bash
+        run: |
+          if command -v sha256sum >/dev/null 2>&1; then
+            sha256sum ${{ matrix.asset_name }} > ${{ matrix.asset_name }}.sha256
+          else
+            shasum -a 256 ${{ matrix.asset_name }} > ${{ matrix.asset_name }}.sha256
+          fi
+          cat ${{ matrix.asset_name }}.sha256
+
+      - name: Create and Upload to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            ${{ matrix.asset_name }}
+            ${{ matrix.asset_name }}.sha256
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Python wheels for PyPI, published as `swiftdoc`. Each wheel holds only the
+  # swiftdoc binary (maturin `bindings = "bin"`, see pyproject.toml), which pip
+  # installs as the `swiftdoc` command. Linux wheels are built in the manylinux
+  # and musllinux containers maturin-action provides.
+  wheels:
+    name: Wheel (${{ matrix.platform }})
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: manylinux-x86_64
+            target: x86_64-unknown-linux-gnu
+            manylinux: auto
+          - os: ubuntu-latest
+            platform: manylinux-aarch64
+            target: aarch64-unknown-linux-gnu
+            manylinux: auto
+          - os: ubuntu-latest
+            platform: musllinux-x86_64
+            target: x86_64-unknown-linux-musl
+            manylinux: musllinux_1_2
+          - os: ubuntu-latest
+            platform: musllinux-aarch64
+            target: aarch64-unknown-linux-musl
+            manylinux: musllinux_1_2
+          - os: macos-latest
+            platform: macos-x86_64
+            target: x86_64-apple-darwin
+          - os: macos-latest
+            platform: macos-aarch64
+            target: aarch64-apple-darwin
+          - os: windows-latest
+            platform: windows-x86_64
+            target: x86_64-pc-windows-msvc
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux }}
+          args: --release --locked --out dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.platform }}
+          path: dist
+
+  sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  # Installs every wheel, and the sdist, on a machine it is meant for and runs
+  # it, so a broken wheel never reaches PyPI.
+  wheel-test:
+    name: Test wheel (${{ matrix.platform }})
+    needs: [wheels, sdist]
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: manylinux-x86_64
+          - os: ubuntu-24.04-arm
+            platform: manylinux-aarch64
+          - os: ubuntu-latest
+            platform: musllinux-x86_64
+            container: python:3.13-alpine
+          - os: ubuntu-24.04-arm
+            platform: musllinux-aarch64
+            container: python:3.13-alpine
+          - os: macos-15-intel
+            platform: macos-x86_64
+          - os: macos-latest
+            platform: macos-aarch64
+          - os: windows-latest
+            platform: windows-x86_64
+          - os: ubuntu-latest
+            platform: sdist
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheels-${{ matrix.platform }}
+          path: dist
+
+      - uses: actions/setup-python@v5
+        if: matrix.container == ''
+        with:
+          python-version: "3.x"
+
+      # --no-index: pip may only use the wheel built above. The sdist needs
+      # maturin from PyPI to build, so it is installed by path instead.
+      - name: Install and run
+        if: matrix.container == ''
+        shell: bash
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: |
+          set -ex
+          if [ "$PLATFORM" = sdist ]; then
+            python -m pip install dist/*.tar.gz
+          else
+            python -m pip install --no-index --find-links dist swiftdoc
+          fi
+          sh scripts/wheel-smoke-test.sh
+
+      - name: Install and run (Alpine container)
+        if: matrix.container != ''
+        env:
+          IMAGE: ${{ matrix.container }}
+        run: |
+          docker run --rm -v "$PWD:/w" -w /w "$IMAGE" sh -c \
+            'pip install --root-user-action=ignore --no-index --find-links dist swiftdoc && sh scripts/wheel-smoke-test.sh'
+
+  # PyPI trusted publishing, so no token is stored. The PyPI project
+  # `swiftdoc` trusts this file (release.yaml) running in the `pypi`
+  # environment of kura120/swiftdoc. `publish` is needed for its check that the
+  # tag matches the Cargo.toml version, which is also the wheel version.
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [publish, wheel-test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/swiftdoc/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: List distributions
+        run: ls -l dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1