diff --git a/.github/workflows/doc-extraction.yml b/.github/workflows/doc-extraction.yml index 932b0d1..2002a8f 100644 --- a/.github/workflows/doc-extraction.yml +++ b/.github/workflows/doc-extraction.yml @@ -2,7 +2,7 @@ name: Extract And Publish Documentation defaults: run: - shell: bash -eo pipefail {0} + shell: 'bash -eo pipefail {0}' on: push: @@ -24,34 +24,48 @@ concurrency: cancel-in-progress: false jobs: - # Build job build: if: github.repository == 'hylo-lang/Lotsawa' runs-on: macos-latest steps: - - name: Checkout - uses: actions/checkout@v3 - - name: Make site Directory - run: mkdir -p _site/docc - - name: Prepare Shell Environment - # The format of the ${GITHUB_ENV} file is extremely restrictive; it apparently only supports - # lines of the form: - # - # = - # - # And a multiline version - # (https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings). - # It is not interpreted directly by a shell, so any quotes or other special characters are - # taken literally. - - # FIXME: REF_URL_COMPONENT computation is probably wrong for some refs. - run: | - echo "REPO_SANS_OWNER=${GITHUB_REPOSITORY##*/} - REF_URL_COMPONENT=${GITHUB_REF##*/} - " >> "${GITHUB_ENV}" + - uses: actions/checkout@v4 + with: + submodules: true + show-progress: false + + - name: Make site Directory + run: mkdir -p _site/docc + + - name: Install Jazzy + run: | + gem install jazzy + + - name: Setup swift + uses: swift-actions/setup-swift@v1 + with: + swift-version: 5.9 - - name: Run DocC + - name: Prepare Shell Environment + # The format of the ${GITHUB_ENV} file is extremely restrictive; it apparently only supports + # lines of the form: + # + # = + # + # And a multiline version + # (https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings). + # It is not interpreted directly by a shell, so any quotes or other special characters are + # taken literally. + + # FIXME: REF_URL_COMPONENT computation is probably wrong for some refs. + run: | + echo "REPO_SANS_OWNER=${GITHUB_REPOSITORY##*/} + REF_URL_COMPONENT=${GITHUB_REF##*/} + LOTSAWA_ENABLE_DOC_GENERATION=1 + " >> "${GITHUB_ENV}" + + - name: Extract with DocC run: | + mkdir -p _site/docc swift package --allow-writing-to-directory ./_site \ generate-documentation \ --product Lotsawa \ @@ -63,10 +77,10 @@ jobs: --source-service github \ --source-service-base-url "https://github.com/${GITHUB_REPOSITORY}/blob/${REF_URL_COMPONENT}" \ --checkout-path "$(pwd)" - - name: Install jazzy - run: gem install jazzy - - name: Run Jazzy + + - name: Extract with Jazzy run: | + mkdir -p _site/jazzy jazzy \ --source-host-files-url "https://github.com/${GITHUB_REPOSITORY}/blob/${REF_URL_COMPONENT}" \ --module Lotsawa \ diff --git a/Package.swift b/Package.swift index 26a16c3..561a588 100644 --- a/Package.swift +++ b/Package.swift @@ -1,11 +1,20 @@ // swift-tools-version: 5.7 import PackageDescription +import Foundation let CitronParser = Target.Dependency.product(name: "CitronParserModule", package: "citron") let CitronLexer = Target.Dependency.product( name: "CitronLexerModule", package: "citron") +/// Dependencies for documentation extraction. +/// +/// Most people don't need to extract documentation; set `HYLO_ENABLE_DOC_GENERATION` in your +/// environment if you do. +let docGenerationDependency: [Package.Dependency] = + ProcessInfo.processInfo.environment["LOTSAWA_ENABLE_DOC_GENERATION"] != nil + ? [.package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.1.0")] : [] + let package = Package( name: "Lotsawa", platforms: [ @@ -20,7 +29,9 @@ let package = Package( .package(url: "https://github.com/dabrahams/citron.git", from: "2.1.1"), .package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.1.0"), .package(url: "https://github.com/SwiftPackageIndex/SPIManifest.git", from: "0.12.0") - ], + ] + + docGenerationDependency, + targets: [ .target( name: "Lotsawa",