From 109eba4c14257aec667c37edeb5242f6fb60afeb Mon Sep 17 00:00:00 2001 From: Florian Friedrich Date: Sat, 7 May 2022 22:35:39 +0200 Subject: [PATCH] Use docc for documentation generation --- .github/workflows/docs.yml | 232 ++++++++++++++++++++++++++++++++++ .github/workflows/release.yml | 69 ---------- .jazzy.yaml | 14 -- Package.swift | 5 + README.md | 2 +- 5 files changed, 238 insertions(+), 84 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 .github/workflows/release.yml delete mode 100644 .jazzy.yaml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..e2745e4 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,232 @@ +name: Publish Documentation + +on: + release: + types: + - published + - edited + push: + branches: [ master ] + +jobs: + release-context: + runs-on: ubuntu-latest + outputs: + version-name: ${{github.ref_name}} + is-latest: ${{steps.compare-tags.output.is-latest}} + steps: + - uses: joutvhu/get-release@v1.0.1 + id: latest-release + with: + latest: true + throwing: false + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + - name: Compare tags + id: compare-tags + run: | + if [ '${{github.ref_type}}' == 'tag' ] && [ '${{steps.latest-release.outputs.tag_name}}' == '${{github.ref_name}}' ]; then + echo "::set-output name=is-latest::true" + else + echo "::set-output name=is-latest::false" + fi + + spm-context: + runs-on: ubuntu-latest + outputs: + package-dump: ${{steps.dump-package.outputs.package-dump}} + steps: + - uses: swift-actions/setup-swift@v1.15.0 + id: swift-setup + with: + swift-version: '5.6' + - name: Read OS Version + uses: sersoft-gmbh/os-version-action@v1.0.0 + id: os-version + - uses: actions/checkout@v3.0.2 + # We don't use a cache here, because SPM doesn't resolve dependencies when dumping packages. + - name: Dump package + id: dump-package + # We need to escape newlines: https://github.community/t/set-output-truncates-multiline-strings/16852/5 + run: | + package_dump="$(swift package dump-package)" + package_dump="${package_dump//'%'/'%25'}" + package_dump="${package_dump//$'\n'/'%0A'}" + package_dump="${package_dump//$'\r'/'%0D'}" + echo "::set-output name=package-dump::${package_dump}" + + generate-docs: + needs: + - release-context + - spm-context + runs-on: ubuntu-latest + strategy: + matrix: + target: ${{fromJson(needs.spm-context.outputs.package-dump).products.*.targets.*}} + steps: + - uses: swift-actions/setup-swift@v1.15.0 + id: swift-setup + with: + swift-version: '5.6' + - name: Read OS Version + uses: sersoft-gmbh/os-version-action@v1.0.0 + id: os-version + - uses: actions/checkout@v3.0.2 + - uses: actions/cache@v3.0.2 + with: + path: .build + key: ${{runner.os}}-${{steps.os-version.outputs.version}}-${{github.repository}}-spm-${{steps.swift-setup.outputs.version}}-${{hashFiles('**/Package.resolved')}} + restore-keys: | + ${{runner.os}}-${{steps.os-version.outputs.version}}-${{github.repository}}-spm-${{steps.swift-setup.outputs.version}}- + - uses: sersoft-gmbh/swifty-docs-action@v2.0.1 + env: + ENABLE_DOCC_SUPPORT: '1' + DOCC_JSON_PRETTYPRINT: 'YES' + with: + package-version: ${{needs.release-context.outputs.version-name}} + targets: ${{matrix.target}} + enable-inherited-docs: true + enable-index-building: false + transform-for-static-hosting: true + hosting-base-path: ${{github.event.repository.name}}/${{needs.release-context.outputs.version-name}} + output: ${{matrix.target}}-docs + - name: Package docs + run: tar -cvf '${{matrix.target}}-docs.tar' '${{matrix.target}}-docs' + - uses: actions/upload-artifact@v3 + with: + name: ${{matrix.target}}-docs + path: ${{matrix.target}}-docs.tar + + publish-docs: + needs: + - release-context + - spm-context + - generate-docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3.0.2 + with: + ref: gh-pages + path: repository + - uses: actions/download-artifact@v3 + with: + path: artifacts + - name: Extract tars + run: find artifacts -name '*.tar' -execdir tar -xvf '{}' --strip-components 1 \; -delete + - name: Merge documentations + env: + TARGETS: ${{join(fromJson(needs.spm-context.outputs.package-dump).products.*.targets.*, ' ')}} + DOCS_BASE_DIR: repository/${{needs.release-context.outputs.version-name}} + run: | + rm -rf "${DOCS_BASE_DIR}" + is_first=1 + for target in $TARGETS; do + if [ $is_first -eq 1 ]; then + echo "Copying initial documentation for ${target}" + cp -R "artifacts/${target}-docs" "${DOCS_BASE_DIR}" + is_first=0 + else + echo "Merging documentation for ${target}" + cp -R "artifacts/${target}-docs/data/documentation/"* "${DOCS_BASE_DIR}/data/documentation/" + cp -R "artifacts/${target}-docs/documentation/"* "${DOCS_BASE_DIR}/documentation/" + fi + done + echo "Deleting non-mergable metadata.json" + rm -f "${DOCS_BASE_DIR}/metadata.json" + - name: Create version index + working-directory: repository + env: + TARGET_DOCS_DIR: ${{needs.release-context.outputs.version-name}}/documentation + INDEX_FILE: ${{needs.release-context.outputs.version-name}}/index.html + BASE_URL: 'https://${{github.repository_owner}}.github.io/${{github.event.repository.name}}/${{needs.release-context.outputs.version-name}}/documentation' + run: | + target_count=0 + target_list="" + single_target_name="" + for target in $(ls "${TARGET_DOCS_DIR}"); do + if [ -d "${TARGET_DOCS_DIR}/${target}" ]; then + single_target_name="${target}" + target_count=$((target_count+1)) + target_list="${target_list}
  • ${target} Documentation
    • " + fi + done + if [ ${target_count} -gt 1 ]; then + echo "Found ${target_count} targets. Generating list..." + cat > "${INDEX_FILE}" < + + + ${{github.event.repository.name}} Documentation + + + + + + EOF + else + echo "Found one target. Generating redirect file to target ${single_target_name}" + cat > "${INDEX_FILE}" < + + + ${{github.event.repository.name}} Documentation + + + +

    Redirecting...

    + + + EOF + fi + - name: Create root index + working-directory: repository + env: + REDIRECT_URL: 'https://${{github.repository_owner}}.github.io/${{github.event.repository.name}}/latest' + run: | + cat > 'index.html' < + + + ${{github.event.repository.name}} Documentation + + + +

    Redirecting...

    + + + EOF + - name: Create latest symlink + if: ${{needs.release-context.outputs.is-latest}} + working-directory: repository + run: | + rm -f 'latest' + ln -s '${{needs.release-context.outputs.version-name}}' 'latest' + - name: Determine changes + id: check-changes + working-directory: repository + run: | + if [ -n "$(git status --porcelain)" ]; then + echo "::set-output name=has-changes::true" + else + echo "::set-output name=has-changes::false" + fi + - uses: crazy-max/ghaction-github-pages@v2.6.0 + if: ${{steps.check-changes.outputs.has-changes}} + with: + keep_history: true + build_dir: repository + commit_message: Deploy documentation for '${{needs.release-context.outputs.version-name}}' + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + + cleanup: + needs: + - generate-docs + - publish-docs + if: always() + runs-on: ubuntu-latest + steps: + - name: Cleanup Artifacts + uses: joutvhu/delete-artifact@v1 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index 6fef87c..0000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,69 +0,0 @@ -name: Release Processing - -on: - release: - types: - - published - - edited - -jobs: - check-release: - runs-on: ubuntu-latest - outputs: - should-publish: ${{steps.compare-tags.outputs.is-latest}} - tag: ${{steps.get-tag.outputs.tag}} - steps: - - uses: thebritican/fetch-latest-release@v2.0.0 - id: latest-release - with: - github_token: ${{secrets.GITHUB_TOKEN}} - - uses: dawidd6/action-get-tag@v1.1.0 - id: get-tag - - id: compare-tags - run: | - if [ '${{steps.latest-release.outputs.tag_name}}' == '${{steps.get-tag.outputs.tag}}' ]; then - echo "::set-output name=is-latest::true" - else - echo "::set-output name=is-latest::false" - fi - - publish-docs: - needs: check-release - if: ${{ needs.check-release.outputs.should-publish == 'true' }} - runs-on: ubuntu-latest - steps: - - uses: maxim-lobanov/setup-xcode@v1.4.1 - if: runner.os == 'macOS' - with: - xcode-version: ^13.0 - - name: Install Swift - if: runner.os == 'Linux' - uses: sersoft-gmbh/swifty-linux-action@v1.3.0 - with: - release-version: 5.6 - github-token: ${{secrets.GITHUB_TOKEN}} - - name: Read OS Version - uses: sersoft-gmbh/os-version-action@v1.0.0 - id: os-version - - name: Read Swift Version - uses: sersoft-gmbh/swift-version-action@v1.0.1 - id: swift-version - - uses: actions/checkout@v3.0.2 - - uses: actions/cache@v3.0.2 - with: - path: .build - key: ${{runner.os}}-${{steps.os-version.outputs.version}}-${{github.repository}}-spm-${{steps.swift-version.outputs.version}}-${{hashFiles('**/Package.resolved')}} - restore-keys: | - ${{runner.os}}-${{steps.os-version.outputs.version}}-${{github.repository}}-spm-${{steps.swift-version.outputs.version}}- - - name: Workaround Package.resolved format issues - if: ${{ startsWith(steps.swift-version.outputs.version, '5.5') }} - run: rm -rf Package.resolved - - uses: sersoft-gmbh/swifty-docs-action@v1.2.1 - with: - module-version: ${{needs.check-release.outputs.tag}} - output: docs - - uses: crazy-max/ghaction-github-pages@v2.6.0 - with: - build_dir: docs - env: - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.jazzy.yaml b/.jazzy.yaml deleted file mode 100644 index 6f1a00d..0000000 --- a/.jazzy.yaml +++ /dev/null @@ -1,14 +0,0 @@ -clean: true - -theme: fullwidth - -output: docs -source_directory: Sources -readme: README.md - -module: RouteDocs -undocumented_text: "" -github_url: https://github.com/sersoft-gmbh/route-docs - -author: ser.soft GmbH -author_url: https://sersoft.de diff --git a/Package.swift b/Package.swift index 1c54c8b..7c80c50 100644 --- a/Package.swift +++ b/Package.swift @@ -2,6 +2,7 @@ // The swift-tools-version declares the minimum version of Swift required to build this package. import PackageDescription +import Foundation let package = Package( name: "route-docs", @@ -42,3 +43,7 @@ let package = Package( dependencies: ["RouteDocs"]), ] ) + +if ProcessInfo.processInfo.environment["ENABLE_DOCC_SUPPORT"] == "1" { + package.dependencies.append(.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")) +} diff --git a/README.md b/README.md index dea0ef7..9044ec0 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ![Tests](https://github.com/sersoft-gmbh/route-docs/workflows/Tests/badge.svg) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/79e8965866ad4ed9a2cf4389c0a3a1a1)](https://www.codacy.com/gh/sersoft-gmbh/route-docs/dashboard?utm_source=github.com&utm_medium=referral&utm_content=sersoft-gmbh/route-docs&utm_campaign=Badge_Grade) [![codecov](https://codecov.io/gh/sersoft-gmbh/route-docs/branch/master/graph/badge.svg?token=UUQetUQ4hG)](https://codecov.io/gh/sersoft-gmbh/route-docs) -[![jazzy](https://raw.githubusercontent.com/sersoft-gmbh/route-docs/gh-pages/badge.svg?sanitize=true)](https://sersoft-gmbh.github.io/route-docs) +[![Docs](https://img.shields.io/badge/-documentation-informational)](https://sersoft-gmbh.github.io/route-docs) This adds some types and extensions to Vapor's `Route` type that allows documenting each route. Also, a `ViewContext` object helps in bringing these documentations to a web page.