Fix documentation generation

.github/workflows/general.yml

@@ -44,7 +44,7 @@ jobs:
         run: tool/gh_actions/analyze_dart_source.sh
 
       - name: Check project documentation
-        run: tool/gh_actions/check_documentation.sh
+        run: tool/gh_actions/generate_documentation.sh
 
       - name: Install software - Icarus Verilog
         run: tool/gh_actions/install_iverilog.sh

tool/gh_actions/generate_documentation.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Copyright (C) 2022-2023 Intel Corporation
+# Copyright (C) 2022-2024 Intel Corporation
 # SPDX-License-Identifier: BSD-3-Clause
 #
 # generate_documentation.sh
@@ -11,12 +11,21 @@
 
 set -euo pipefail
 
-# See script "check_documentation.sh" for a note on processing "dart doc" output.
+# Output parsing is required because "dart doc" is not capable of
+# signaling a warning with an exit code:
+#   https://github.com/dart-lang/dartdoc/issues/2846
+#   https://github.com/dart-lang/dartdoc/issues/2907
+#   https://github.com/dart-lang/dartdoc/issues/1959
 
-# The documentation will be placed in the "doc/api" folder.
-output=$(dart doc --validate-links 2>&1 | tee)
-
-echo "${output}"
+# Disabling --validate-links due to https://github.com/dart-lang/dartdoc/issues/3584
+# output=$(dart doc --validate-links 2>&1 | tee)
+output=$(dart doc 2>&1 | tee)
 
 # In case of problems, the searched substring will not be found.
-echo "${output}" | grep --silent 'no issues found'
+if echo "${output}" | grep --silent -e 'no issues found' -e 'Success!'; then
+  echo 'Documentation check passed!'
+else
+  echo "${output}"
+  echo 'Documentation failed since some issues were found'
+  exit 1
+fi

tool/run_checks.sh

@@ -103,7 +103,7 @@ tool/gh_actions/analyze_dart_source.sh
 
 # Check project documentation
 print_step 'Check project documentation'
-tool/gh_actions/check_documentation.sh
+tool/gh_actions/generate_documentation.sh
 
 # Verify python formatting
 print_step 'Verify python formatting'