Typedoc: separate extract and document operations

.changeset/proud-donkeys-count.md

@@ -0,0 +1,5 @@
+---
+"@siteimprove/alfa-toolchain": minor
+---
+
+**Added:** A new "alfa-markdown" theme is available for typedoc's markdown generation.

.github/actions/documentation/action.yaml

@@ -1,6 +1,11 @@
 name: Generate documentation
 description: This re-generates the API documentation and pushes it.
 
+inputs:
+  version-tag:
+    description: "The git tag to use as version for source links"
+    required: true
+
 runs:
   using: composite
 
@@ -14,14 +19,20 @@ runs:
         echo "This workflow can only be called from the main branch."
         exit 1
 
-    - name: Extract API documentation
+    - name: Extract API documentation (API extractor)
       shell: bash
       run: yarn extract
 
-    - name: Generate text documentation
+    - name: Generate text documentation (API documenter)
       shell: bash
       run: yarn document
 
+    - name: Generate HTML/Markdown/JSON documentation (Typedoc)
+      shell: bash
+      run: yarn typedoc-document
+      env:
+        ALFA_DOC_VERSION: ${{ inputs.version-tag }}
+
     - name: Stage changes
       shell: bash
       # Find in current directory.
@@ -34,6 +45,8 @@ runs:
         -name node_modules -prune
         -o
         -wholename "./*docs/api/*" -print0
+        -o
+        -wholename "./*docs/typedoc/*" -print0
         | xargs -0 git add
 
 

.github/actions/version/action.yaml

@@ -3,6 +3,11 @@ description:
   "This workflow creates a new version, update packages and changelogs, and push the changes.
   It does not actually publish the packages, see .github/actions/publish/action.yml."
 
+inputs:
+  reference-package:
+    description: "The package whose (new) version to use as 'new version'"
+    default: "@siteimprove/alfa-rules"
+
 outputs:
   version:
     description: "The new version"
@@ -33,11 +38,26 @@ runs:
         GITHUB_TOKEN: ${{ github.token }}
 
     - name: Get new version
-      # This is needed to push the correct git tag
+      # The "source of truth" for the new version is inputs.package, which can be either a local package (workspace)
+      # or a dependency. We first look for it as a local package, else in node_modules.
       id: new
       shell: bash
       run: |
-        echo "version=$(grep \"version\": */alfa-*/package.json | cut -d\" -f 4 | sort -u)" >> $GITHUB_OUTPUT
+        node -e "
+          const fs = require('node:fs');
+          const { execSync } = require('node:child_process');
+          const pkgName = process.env.INPUT_PACKAGE;
+          const workspaces = execSync('yarn workspaces list --json', {encoding: 'utf8'})
+            .trim().split('\n').map(JSON.parse);
+          const ws = workspaces.find(w => w.name === pkgName);
+          const pkgJson = ws
+            ? JSON.parse(fs.readFileSync(ws.location + '/package.json', 'utf8'))
+            : JSON.parse(fs.readFileSync('node_modules/' + pkgName + '/package.json', 'utf8'));
+          console.log('version=' + pkgJson.version);
+        "
+        >> $GITHUB_OUTPUT
+      env:
+        INPUT_PACKAGE: ${{ inputs.reference-package }}
 
     - name: Run post version scripts
       shell: bash
@@ -89,13 +109,12 @@ runs:
         -name "package.json" -print0
         | xargs -0 git add
 
-    - name: Commit and tag changes
+    - name: Commit changes
       shell: bash
       # If the version has changed, there is something to commit. Otherwise, changeset should have failed.
       # So we do not allow empty commit and fail if one happens.
       run: |
         git commit --message=${VERSION}
-        git tag --annotate ${VERSION} --message=${VERSION}
       env:
         # Passing it as a variable rather than inline hardens against script injection.
         # See https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable

.github/actions/wrapper/action.yaml

@@ -30,6 +30,9 @@ inputs:
     description: "Whether to create and publish a new version."
     required: false
     default: "false"
+  reference-package:
+    description: "Which package's version will be used to tag the release (default: @siteimprove/alfa-rules)."
+    required: false
   public:
     description: "Whether the packages are public and require a provenance statement."
     required: false
@@ -65,26 +68,40 @@ runs:
         # We only need graphviz to generate dependency graphs
         setup-graphviz: ${{ inputs.dependency-graphs }}
 
+    - name: Bump version
+      id: version
+      if: inputs.publish == 'true'
+      uses: siteimprove/alfa/.github/actions/version@main
+      with:
+        reference-package: ${{ input.reference-package }}
+
     - name: Generate coverage data
       if: inputs.coverage == 'true'
       uses: siteimprove/alfa/.github/actions/coverage@main
 
     - name: Generate documentation
       if: inputs.generate-documentation == 'true'
       uses: siteimprove/alfa/.github/actions/documentation@main
+      with:
+        version-tag: v${{ steps.version.outputs.version }}
 
     - name: Generate dependency graphs
       if: inputs.dependency-graphs == 'true'
       uses: siteimprove/alfa/.github/actions/dependency-graphs@main
 
-    - name: Bump version
-      id: version
-      if: inputs.publish == 'true'
-      uses: siteimprove/alfa/.github/actions/version@main
+    - name: Add version tag
+      shell: bash
+      if: input.publish == 'true'
+      run: git tag --annotate ${VERSION} --message=${VERSION}
+      env:
+        # Passing it as a variable rather than inline hardens against script injection.
+        # See https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable
+        VERSION: v${{ steps.version.outputs.version }}
+
 
     - name: Push changes
       shell: bash
-      # "version" may create a new tag, so we need to push tags too.
+      # New version creates a new tag, so we need to push tags too.
       run: git push --follow-tags
 
     - name: Publish packages

config/typedoc.mjs

@@ -1,43 +1,155 @@
+// We use environment variabales to pass parameters because the script
+// invokation is mangled into yarn and typedoc own invokations.
+
+// Check that we have a target (review/documentation)
+const target = process.env.ALFA_DOC_TARGET;
+if (target !== "review" && target !== "documentation") {
+  console.error(
+    `Need one ALFA_DOC_TARGET of either "review" or "documentation"`,
+  );
+  process.exit(1);
+}
+
+// Set up the source link parameters and choose outputs, based on target.
+// * For "review", we generate Markdown with a stable source link (main branch,
+//   no line number) and minimum text, as this is meant to be shipped with every
+//   PR and we want to avoid changes due to irrelevant details (git hash or
+//   adding a new line and changing numbers).
+// * For "documentation", we generate Markdown,  HTML and JSON, linking to the
+//   git tag of the release. The tag cannot be guessed, as it should not have
+//   been created yet, as the newer documentation must be part of that tag… So
+//   we also pass it along. The JSON documentation is used for merging with
+//   other repos.
+let gitRevision;
+let disableSources;
+let review = false;
+let markdown = false;
+let html = false;
+let json = false;
+
+if (target === "review") {
+  review = true;
+  gitRevision = "main";
+  disableSources = true;
+}
+
+if (target === "documentation") {
+  // Adapted from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+  // by adding the starting "v" and ending the line after the 3 numbers.
+  // This matches what we use for tags when making a release.
+  const semVerRegex =
+    // start of line
+    // v
+    // Three identical capture groups, separated by dots.
+    //   Each group is either 0 or any number of digits, starting with a non-0.
+    // end of line
+    /^v(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)$/;
+  if ((process.env.ALFA_DOC_VERSION ?? "").match(semVerRegex) === null) {
+    console.error(
+      `An ALFA_DOC_TARGET of "documentation" requires an ALFA_DOC_VERSION of "vx.y.z" with three numbers x, y, and z`,
+    );
+    process.exit(2);
+  }
+  markdown = true;
+  html = true;
+  json = true;
+  gitRevision = process.env.ALFA_DOC_VERSION;
+}
+
+// Validation
+if (review && markdown) {
+  console.error(
+    "'review' and 'markdown' cannot be generated together as they use the same post-processor, with different options",
+  );
+  process.exit(3);
+}
+
+// Set up the outputs parameters.
+const outputs = [];
+if (html) {
+  outputs.push({ name: "html", path: "../docs/typedoc/html" });
+}
+if (json) {
+  outputs.push({ name: "json", path: "../docs/typedoc/json" });
+}
+if (markdown) {
+  outputs.push({
+    name: "markdown",
+    path: "../docs/typedoc/markdown",
+    options: {
+      indexFormat: "table",
+      parametersFormat: "table",
+      interfacePropertiesFormat: "table",
+      classPropertiesFormat: "table",
+      typeAliasPropertiesFormat: "table",
+      enumMembersFormat: "table",
+      propertyMembersFormat: "table",
+      typeDeclarationFormat: "table",
+      pageTitleTemplates: {
+        // While Classes do have their kind added to the page, Namespace don't
+        // as they are usually used as modules, but in our case we want the
+        // kind to show on the documentation page.
+        module: (args) =>
+          args.kind === "Namespace" ? `${args.kind}: ${args.name}` : args.name,
+      },
+      // Add the kind to reflections with the same name in a table (typically
+      // class/diagnostic).
+      theme: ["categorizeMarkdown"],
+    },
+  });
+}
+
+if (review) {
+  outputs.push({
+    name: "markdown",
+    path: "../docs/typedoc/review",
+    options: {
+      parametersFormat: "table",
+      hidePageHeader: true,
+      hideBreadcrumbs: true,
+      useCodeBlocks: true,
+      expandObjects: true,
+      expandParameters: true,
+      pageTitleTemplates: {
+        // While Classes do have their kind added to the page, Namespace don't
+        // as they are usually used as modules, but in our case we want the
+        // kind to show on the documentation page.
+        module: (args) =>
+          args.kind === "Namespace" ? `${args.kind}: ${args.name}` : args.name,
+      },
+      // Add the kind to reflections with the same name in a table (typically
+      // class/diagnostic), and remove line number from links' names.
+      theme: ["reviewTheme"],
+    },
+  });
+}
+
 /** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions} */
 export default {
   name: "Alfa API documentation",
-  entryPoints: ["../packages/alfa-*"],
+  entryPoints: ["../packages/alfa-act", "../packages/alfa-dom"],
   entryPointStrategy: "packages",
   readme: "none",
   includeVersion: true,
   excludeExternals: true,
+  packageOptions: {
+    entryPoints: ["src/index.ts"],
+    gitRevision,
+    disableSources,
+    readme: "none",
+    includeVersion: true,
+    excludeExternals: true,
+    excludeInternal: false,
+    jsDocCompatibility: false,
+    excludeTags: ["@knipignore"],
+    sort: ["alphabetical", "kind"],
+  },
   plugin: [
     "@siteimprove/alfa-toolchain/typedoc-plugin-categorize",
+    "@siteimprove/alfa-toolchain/typedoc-markdown-theme-review",
     "typedoc-plugin-markdown",
   ],
-  outputs: [
-    { name: "html", path: "../docs/typedoc/html" },
-    { name: "json", path: "../docs/typedoc/json" },
-    {
-      name: "markdown",
-      path: "../docs/typedoc/markdown",
-      options: {
-        indexFormat: "table",
-        parametersFormat: "table",
-        interfacePropertiesFormat: "table",
-        classPropertiesFormat: "table",
-        typeAliasPropertiesFormat: "table",
-        enumMembersFormat: "table",
-        propertyMembersFormat: "table",
-        typeDeclarationFormat: "table",
-        pageTitleTemplates: {
-          // While Classes do have their kind added to the page, Namespace don't
-          // as they are usually used as modules, but in our case we want the
-          // kind to show on the documentation page.
-          module: (args) =>
-            args.kind === "Namespace"
-              ? `${args.kind}: ${args.name}`
-              : args.name,
-        },
-        theme: "categorizeMarkdown",
-      },
-    },
-  ],
+  outputs,
   router: "structure",
   favicon: "../media/icon.svg",
   sourceLinkExternal: true,