Documentation extraction and publishing (hylo-lang#836)

.github/workflows/doc-extraction.yml

@@ -0,0 +1,141 @@
+name: Extract And Publish Documentation
+
+defaults:
+  run:
+    shell: bash -eo pipefail {0}
+
+on:
+  push:
+    branches: [ main ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v3
+    - run: git config --global core.autocrlf input
+
+    - name: Setup swift
+      uses: swift-actions/setup-swift@v1
+      with:
+        swift-version: 5.8
+
+    - run: swift --version
+
+    - name: Setup LLVM
+      uses: KyleMayes/install-llvm-action@v1
+      with:
+        version: "15.0"
+
+    - run: llvm-config --version
+
+    - name: Prepare Shell Environment
+      # The format of the ${GITHUB_ENV} file is extremely restrictive; it apparently only supports
+      # lines of the form:
+      #
+      #   <variable-name>=<one-line-of-text>
+      #
+      # 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 "PKG_CONFIG_PATH=$PWD
+        REPO_SANS_OWNER=${GITHUB_REPOSITORY##*/}
+        REF_URL_COMPONENT=${GITHUB_REF##*/}
+        EXTRACTION_TARGETS=$(
+          swift package dump-package |
+          jq '.targets | map(select(.type | test("^(regular|executable)$"))) | .[].name' |
+          xargs
+        )
+        " >> "${GITHUB_ENV}"
+
+    - name: Generate LLVM pkgconfig file
+      run: |
+        swift package resolve
+        .build/checkouts/Swifty-LLVM/Tools/make-pkgconfig.sh llvm.pc
+        cat llvm.pc
+
+    - name: Extract with DocC
+      run: |
+        export PKG_CONFIG_PATH
+        for TARGET in ${EXTRACTION_TARGETS}; do
+          mkdir -p _site/docc/"$TARGET"
+          swift package --allow-writing-to-directory ./_site \
+          generate-documentation \
+          --target "$TARGET" \
+          --output-path _site/docc/"${TARGET}" \
+          --experimental-documentation-coverage --level brief \
+          --enable-inherited-docs \
+          --transform-for-static-hosting \
+          --hosting-base-path "${REPO_SANS_OWNER}/docc/${TARGET}" \
+          --source-service github \
+          --source-service-base-url "https://github.com/${GITHUB_REPOSITORY}/blob/${REF_URL_COMPONENT}" \
+          --checkout-path "$(pwd)"
+        done
+
+    - name: Extract with Jazzy
+      run: |
+        export PKG_CONFIG_PATH
+        gem install jazzy
+        for TARGET in ${EXTRACTION_TARGETS}; do
+          mkdir -p _site/jazzy/"$TARGET"
+          jazzy \
+          --source-host-files-url "https://github.com/${GITHUB_REPOSITORY}/blob/${REF_URL_COMPONENT}" \
+          --module "$TARGET" \
+          --module-version "${{ github.event.release.tag_name }}" \
+          --copyright "© $(date '+%Y') The Hylo Authors. (Last updated: $(date '+%Y-%m-%d'))" \
+          --config .jazzy.yml \
+          --output _site/jazzy/"$TARGET" \
+          --min-acl private
+        done
+
+    - name: Generate Index Page
+      run: |
+        Tools/gyb.py \
+        --line-directive '<!-- file: %(file)s line: %(line)s -->' \
+        -DROOT_URL="https://hylo-lang.org/${REPO_SANS_OWNER}" \
+        -DEXTRACTION_TARGETS="${EXTRACTION_TARGETS}" \
+        -DGITHUB_REPOSITORY="${GITHUB_REPOSITORY}" \
+        Tools/doc-index.html.gyb -o _site/index.html
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v3
+
+    - name: Fix permissions
+      run: |
+        chmod -v -R +rX "_site/" | while read line; do
+          echo "::warning title=Invalid file permissions automatically fixed::$line"
+        done
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v2
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.jazzy.yml

@@ -0,0 +1,5 @@
+module: Hylo
+author: Dimi Racordon
+theme: fullwidth
+author_url: "https://hylo-lang.dev"
+github_url: "https://github.com/hylo-lang"

Package.resolved

@@ -45,6 +45,24 @@
         "version" : "1.0.4"
       }
     },
+    {
+      "identity" : "swift-docc-plugin",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-plugin.git",
+      "state" : {
+        "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-docc-symbolkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-symbolkit",
+      "state" : {
+        "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+        "version" : "1.0.0"
+      }
+    },
     {
       "identity" : "swift-format",
       "kind" : "remoteSourceControl",

Package.swift

@@ -36,6 +36,7 @@ let package = Package(
     .package(
       url: "https://github.com/apple/swift-format",
       from: "508.0.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"),

Plugins/TestGeneratorPlugin/TestGeneratorPlugin.swift

@@ -11,7 +11,7 @@ struct TestGeneratorPlugin: BuildToolPlugin {
     let outputPath = context.pluginWorkDirectory.appending("HyloFileTests.swift")
 
     let cmd = Command.buildCommand(
-      displayName: "Generating XCTestCases for \(inputPaths.map(\.stem)) into \(outputPath)",
+      displayName: "Generating XCTestCases into \(outputPath)",
       executable: try context.tool(named: "GenerateHyloFileTests").path,
       arguments: ["-o", outputPath, "-n", target.moduleName] + inputPaths,
       inputFiles: inputPaths,

Tools/doc-index.html.gyb

@@ -0,0 +1,67 @@
+
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+<!-- Begin Jekyll SEO tag v2.8.0 -->
+<title>${GITHUB_REPOSITORY} Implementation Documentation</title>
+<meta name="generator" content="Jekyll v3.9.3" />
+<meta property="og:title" content="${GITHUB_REPOSITORY}" />
+<meta property="og:locale" content="en_US" />
+<meta name="description" content="${GITHUB_REPOSITORY} Implementation Documentation" />
+<meta property="og:description" content="${GITHUB_REPOSITORY} Implementation Documentation" />
+<link rel="canonical" href="${ROOT_URL}/index.html" />
+<meta property="og:url" content="${ROOT_URL}/index.html" />
+<meta property="og:site_name" content="Hylo" />
+<meta property="og:type" content="website" />
+<meta name="twitter:card" content="summary" />
+<meta property="twitter:title" content="Hylo" />
+<script type="application/ld+json">
+{"@context":"https://schema.org","@type":"WebPage","description":"The Hylo Programming Language","headline":"Hylo","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://www.hylo-lang.org/assets/img/logo.svg"}},"url":"https://www.hylo-lang.org/pages/implementation-status.html"}</script>
+<!-- End Jekyll SEO tag -->
+
+    <link rel="stylesheet" href="/./assets/css/page.css?v=a558f3689fd693bc688981491b574e4a03787d25">
+    <!--[if lt IE 9]>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+    <div class="wrapper">
+      <header>
+
+          <img src="/assets/img/logo.svg" alt="Logo" />
+
+
+        <p>The Hylo Programming Language</p>
+
+
+<p class="view"><a href="https://docs.hylo-lang.org/language-tour/">Language tour</a></p>
+<p class="view"><a href="/pages/implementation-status.html">Roadmap</a></p>
+<p class="view"><a href="https://github.com/orgs/hylo-lang/discussions">Community discussion</a></p>
+
+
+
+      </header>
+      <section>
+	<h1>${GITHUB_REPOSITORY} Implementation Documentation</h1>
+	<p>None of the available documentation extraction tools can merge and cross-link
+	documentation from different targets, so they are presented separately and each has its own
+	link.</p>
+	<h2>Targets</h2>
+	<ul>
+% for m in EXTRACTION_TARGETS.split(" "):
+          <li>${m} (<a href="docc/${m}/documentation/${m.lower()}">docc</a>, <a href="jazzy/${m}">jazzy</a>)</li>
+% end
+	</ul>
+      </section>
+      <footer>
+
+        <p><small>Hosted on GitHub Pages &mdash; Theme by <a href="https://github.com/orderedlist">orderedlist</a></small></p>
+      </footer>    </div>
+    <script src="/./assets/js/scale.fix.js"></script>
+
+  </body>
+</html>