Build: added steps to generate packages api documentation. (#27930)

* added steps to generate docs. * re-generated the drone.yml file. * removed metrics reporting from pr pipeline. * fixed spelling issues. * fixed so package generation should work. * some small refactorings. * fixed spelling error. * adding echo to verify that we execute the correct script. * removed echo statement. * changed scripts a bit. * added ci flag to script. * adding exit 1 * increased the limit. * added missing space. * fixed shellcheck error. * fixing lint errors. * renamed build step. * changed logic. * increased limit. * changed to echo instead of echo -e * fixed shellcheck errors. * trying to debug script, * trying to simplify the find statement. * fixed issue with text formatting on linux. * imported build step. * Update scripts/ci-reference-docs-lint.sh Co-authored-by: Arve Knudsen <arve.knudsen@gmail.com> * removed cleanup of packages. * increased limit. * will build frontend docs on master but not lint it. * will always run the linting step. Co-authored-by: Arve Knudsen <arve.knudsen@gmail.com>
2025-02-25 18:55:37 -06:00 · 2020-10-14 14:35:55 +02:00 · 2020-10-14 14:35:55 +02:00 · b5196f531c
commit b5196f531c
parent f22b768ce4
9 changed files with 123 additions and 60 deletions
--- a/.drone.yml
+++ b/.drone.yml
@ -143,6 +143,13 @@ steps:
  depends_on:
  - package

+- name: build-frontend-docs
+  image: grafana/build-container:1.2.27
+  commands:
+  - ./scripts/ci-reference-docs-lint.sh ci
+  depends_on:
+  - build-frontend
+
 - name: build-docs-website
  image: grafana/docs-base:latest
  commands:
@ -151,6 +158,7 @@ steps:
  - cd /hugo && make prod
  depends_on:
  - initialize
+  - build-frontend-docs

 - name: copy-packages-for-docker
  image: grafana/build-container:1.2.27
@ -441,6 +449,13 @@ steps:
  depends_on:
  - build-storybook

+- name: build-frontend-docs
+  image: grafana/build-container:1.2.27
+  commands:
+  - ./scripts/ci-reference-docs-lint.sh ci
+  depends_on:
+  - build-frontend
+
 - name: build-docs-website
  image: grafana/docs-base:latest
  commands:
@ -449,6 +464,7 @@ steps:
  - cd /hugo && make prod
  depends_on:
  - initialize
+  - build-frontend-docs

 - name: copy-packages-for-docker
  image: grafana/build-container:1.2.27
--- a/package.json
+++ b/package.json
@ -26,6 +26,7 @@
    "packages:publishNext": "lerna publish from-package --contents dist --dist-tag next --yes",
    "packages:publishDev": "lerna publish from-package --contents dist --dist-tag dev --yes --registry http://grafana-npm.local:4873 --force-publish=*",
    "packages:typecheck": "lerna run typecheck",
+    "packages:clean": "lerna run clean",
    "precommit": "grafana-toolkit precommit",
    "prettier:check": "prettier --list-different \"**/*.{ts,tsx,scss}\"",
    "prettier:write": "prettier --list-different \"**/*.{ts,tsx,scss}\" --write",
@ -74,7 +75,6 @@
    "@emotion/core": "10.0.27",
    "@grafana/api-documenter": "0.9.3",
    "@grafana/eslint-config": "2.0.3",
-    "@microsoft/api-extractor": "7.8.2-pr1796.0",
    "@rtsao/plugin-proposal-class-properties": "7.0.1-patch.1",
    "@testing-library/jest-dom": "^5.11.3",
    "@testing-library/react": "^10.4.8",
@ -205,6 +205,7 @@
    "zone.js": "0.7.8"
  },
  "dependencies": {
+    "@grafana/api-extractor": "7.10.1",
    "@grafana/slate-react": "0.22.9-grafana",
    "@reduxjs/toolkit": "1.3.4",
    "@torkelo/react-select": "3.0.8",
--- a/packages/grafana-ui/src/components/BigValue/BigValue.story.tsx
+++ b/packages/grafana-ui/src/components/BigValue/BigValue.story.tsx
@ -51,6 +51,7 @@ export const basic = () => {

  return (
    <BigValue
+      // eslint-disable-next-line react-hooks/rules-of-hooks
      theme={useTheme()}
      width={width}
      height={height}
--- a/scripts/ci-reference-docs-build.sh
+++ b/scripts/ci-reference-docs-build.sh
@ -3,9 +3,16 @@
 # abort if we get any error
 set -eo pipefail

-# building grafana packages
-echo "building grafana packages..."
-yarn packages:build
+BUILD_MODE="${1-local}"
+
+if [ "local" == "$BUILD_MODE" ]
+  then
+    # building grafana packages
+    echo "building grafana packages..."
+    yarn packages:build
+  else
+    echo "skip building grafana packages since it already built in previous steps..."
+fi

 # extract packages api documentation json
 echo "extracting packages documentation data..."
@ -14,7 +21,3 @@ yarn packages:docsExtract
 # generating api documentation markdown
 echo "generating markdown from documentation data..."
 yarn packages:docsToMarkdown
-
-# cleaning packages
-echo "cleaning up packages build files..."
-lerna run clean
--- a/scripts/ci-reference-docs-metrics.sh
+++ b/scripts/ci-reference-docs-metrics.sh
@ -3,49 +3,42 @@
 # abort if we get any error
 set -eo pipefail

-report_reference_docs_metrics() {
-  # $1 = branch that the script is running on.
-  # $2 = number of warnings in current version of the code.
-
-  if [ "${1}" == "master" ]; then
-  ./scripts/ci-metrics-publisher.sh \
-    grafana.ci-code.reference-docs.warnings="$2"
-  fi
-}
-
 pretty_print_result_of_report() {
  # $1 = result of current report

  echo -e "\n\n"
  echo -e "-----------------------------------------------------\n"
  echo -e "$1\n"
-  echo -e "-----------------------------------------------------"
+  echo "-----------------------------------------------------"
 }

+BUILD_MODE="${1-local}"
 REPORT_PATH="$(realpath "$(dirname "$0")/../reports/docs/")"
 BUILD_SCRIPT_PATH="$(realpath "$(dirname "$0")/ci-reference-docs-build.sh")"

 if [ ! -d "$REPORT_PATH" ]; then
  # this script needs to be run after the packages have been built and the api-extractor has completed.
  # shellcheck source=/scripts/ci-reference-docs-build.sh
-  . "$BUILD_SCRIPT_PATH"
+  if ! . "$BUILD_SCRIPT_PATH" "$BUILD_MODE";
+    then
+      echo "Failed to build packages and extract docs" >&2
+      exit 1
+    else
+      echo "Successfully built packages and extracted docs"
+  fi
 fi

-WARNINGS_COUNT="$(find "$REPORT_PATH" -type f -name \*.log -print0 | xargs -0 grep -o "\[33mWarning:" | wc -l | xargs)"
-WARNINGS_COUNT_LIMIT=900
+WARNINGS_COUNT="$(find "$REPORT_PATH" -type f -name \*.log -print0 | xargs -0 grep -o "Warning: " | wc -l | xargs)"
+WARNINGS_COUNT_LIMIT=1077

 if [ "$WARNINGS_COUNT" -gt $WARNINGS_COUNT_LIMIT ]; then
  echo -e "API Extractor warnings/errors $WARNINGS_COUNT exceeded $WARNINGS_COUNT_LIMIT so failing build.\n"
-  echo -e "Please go to: https://github.com/grafana/grafana/blob/master/contribute/style-guides/code-comments.md for more information on how to add code comments."
-  report_reference_docs_metrics "$CIRCLE_BRANCH" "$WARNINGS_COUNT"
+  echo "Please go to: https://github.com/grafana/grafana/blob/master/contribute/style-guides/code-comments.md for more information on how to add code comments."
  exit 1
 fi

 if [ "$WARNINGS_COUNT" -lt $WARNINGS_COUNT_LIMIT ]; then
  pretty_print_result_of_report "Wohoo! Fewer warnings compared to last build 🎉🎈🍾✨\n\nYou can lower the threshold from $WARNINGS_COUNT_LIMIT to $WARNINGS_COUNT in the:\nscripts/ci-reference-docs-metrics.sh"
-  report_reference_docs_metrics "$CIRCLE_BRANCH" "$WARNINGS_COUNT"
-  exit 0
 fi

 pretty_print_result_of_report "API Extractor total warnings: $WARNINGS_COUNT"
-report_reference_docs_metrics "$CIRCLE_BRANCH" "$WARNINGS_COUNT"
--- a/scripts/lib.star
+++ b/scripts/lib.star
@ -383,6 +383,21 @@ def build_frontend_step(edition, ver_mode, is_downstream=False):
        ],
    }

+def build_frontend_docs_step(edition):
+    if edition == 'enterprise':
+        return None
+
+    return {
+        'name': 'build-frontend-docs',
+        'image': build_image,
+        'depends_on': [
+            'build-frontend'
+        ],
+        'commands': [
+            './scripts/ci-reference-docs-lint.sh ci',
+        ]
+    }
+
 def build_plugins_step(edition, sign=False):
    if sign:
        env = {
@ -603,6 +618,7 @@ def build_docs_website_step():
        'image': 'grafana/docs-base:latest',
        'depends_on': [
            'initialize',
+            'build-frontend-docs',
        ],
        'commands': [
            'mkdir -p /hugo/content/docs/grafana',
--- a/scripts/master.star
+++ b/scripts/master.star
@ -13,6 +13,7 @@ load(
    'e2e_tests_server_step',
    'e2e_tests_step',
    'build_storybook_step',
+    'build_frontend_docs_step',
    'build_docs_website_step',
    'copy_packages_for_docker_step',
    'build_docker_images_step',
@ -52,6 +53,7 @@ def get_steps(edition, is_downstream=False):
        e2e_tests_step(),
        build_storybook_step(edition=edition, ver_mode=ver_mode),
        publish_storybook_step(edition=edition, ver_mode=ver_mode),
+        build_frontend_docs_step(edition=edition),
        build_docs_website_step(),
        copy_packages_for_docker_step(),
        build_docker_images_step(edition=edition, ver_mode=ver_mode, publish=publish),
--- a/scripts/pr.star
+++ b/scripts/pr.star
@ -13,6 +13,7 @@ load(
    'e2e_tests_server_step',
    'e2e_tests_step',
    'build_storybook_step',
+    'build_frontend_docs_step',
    'build_docs_website_step',
    'copy_packages_for_docker_step',
    'build_docker_images_step',
@ -42,6 +43,7 @@ def pr_pipelines(edition):
        e2e_tests_server_step(),
        e2e_tests_step(),
        build_storybook_step(edition=edition, ver_mode=ver_mode),
+        build_frontend_docs_step(edition=edition),
        build_docs_website_step(),
        copy_packages_for_docker_step(),
        build_docker_images_step(edition=edition, ver_mode=ver_mode, archs=['amd64',]),
--- a/yarn.lock
+++ b/yarn.lock
@ -3336,6 +3336,23 @@
    js-yaml "~3.13.1"
    resolve "1.8.1"

+"@grafana/api-extractor@7.10.1":
+  version "7.10.1"
+  resolved "https://registry.yarnpkg.com/@grafana/api-extractor/-/api-extractor-7.10.1.tgz#9464911c20483485cf042586dc594f4184702b55"
+  integrity sha512-TpfRiHvR9gkjtZWSpOsdnHvSuIFIy//FhQtOcEtBzotiHiaH/b+qTcaHHondVS2r5MNWj3zfcVBRR1S1Yx5cUQ==
+  dependencies:
+    "@microsoft/api-extractor-model" "workspace:*"
+    "@microsoft/tsdoc" "0.12.19"
+    "@rushstack/node-core-library" "workspace:*"
+    "@rushstack/rig-package" "workspace:*"
+    "@rushstack/ts-command-line" "workspace:*"
+    colors "~1.2.1"
+    lodash "~4.17.15"
+    resolve "~1.17.0"
+    semver "~7.3.0"
+    source-map "~0.6.1"
+    typescript "~3.9.7"
+
 "@grafana/data@7.0.0", "@grafana/data@next":
  version "7.0.0"
  resolved "https://registry.yarnpkg.com/@grafana/data/-/data-7.0.0.tgz#89dff54c6a9bf21536beb21e2882880572a84837"
@ -4829,28 +4846,13 @@
    "@microsoft/node-core-library" "3.19.3"
    "@microsoft/tsdoc" "0.12.14"

-"@microsoft/api-extractor-model@7.8.0":
-  version "7.8.0"
-  resolved "https://registry.yarnpkg.com/@microsoft/api-extractor-model/-/api-extractor-model-7.8.0.tgz#5f532998f01109f23d57b422803bbdf5ad655d80"
-  integrity sha512-rk3n2GJ2DyKsmKmSK0VYN92ZAWPgc5+zBLbGASpty3pBZBuByJ0ioZdkxbtm5gaeurJzsG9DFTPCmpg/+Mt/nw==
+"@microsoft/api-extractor-model@workspace:*":
+  version "7.10.3"
+  resolved "https://registry.yarnpkg.com/@microsoft/api-extractor-model/-/api-extractor-model-7.10.3.tgz#f687f324e940bd71e3e73b5b262a54594b0ea61c"
+  integrity sha512-etP4NbZpj+zPCuO3YYigIYXkXq5zYhfE3vo/hrCj1OOd/159HDbSHnEQrNWRVy5TR79RAzHvkYAwtLYKeYP8Ag==
  dependencies:
    "@microsoft/tsdoc" "0.12.19"
-    "@rushstack/node-core-library" "3.19.7"
-
-"@microsoft/api-extractor@7.8.2-pr1796.0":
-  version "7.8.2-pr1796.0"
-  resolved "https://registry.yarnpkg.com/@microsoft/api-extractor/-/api-extractor-7.8.2-pr1796.0.tgz#1a174168c7a9a07d9c1790508fc71331ee36a8fe"
-  integrity sha512-Yc22e1j3TTJezL805KCSiuegjCdi24AXaEjGDSox2kF2X4VIGdrwRnCv5LPOVp0SbEDq13aPTVwby9y+A+OMCg==
-  dependencies:
-    "@microsoft/api-extractor-model" "7.8.0"
-    "@microsoft/tsdoc" "0.12.19"
-    "@rushstack/node-core-library" "3.19.7"
-    "@rushstack/ts-command-line" "4.4.0"
-    colors "~1.2.1"
-    lodash "~4.17.15"
-    resolve "1.8.1"
-    source-map "~0.6.1"
-    typescript "~3.7.2"
+    "@rushstack/node-core-library" "3.34.3"

 "@microsoft/node-core-library@3.19.3":
  version "3.19.3"
@ -5123,27 +5125,39 @@
    "@babel/helper-replace-supers" "^7.0.0"
    "@babel/plugin-syntax-class-properties" "^7.0.0"

-"@rushstack/node-core-library@3.19.7":
-  version "3.19.7"
-  resolved "https://registry.yarnpkg.com/@rushstack/node-core-library/-/node-core-library-3.19.7.tgz#8d8a193fd6f99536c92dd797ab50fd5fcb7630ea"
-  integrity sha512-gKE/OXH5GAj8yJ1kEyRW68UekJernilZ3QTRgmQ0MUHBCQmtZ9Q6T5PQ1sVbcL4teH8BMdpZeFy1DKnHs8h3PA==
+"@rushstack/node-core-library@3.34.3", "@rushstack/node-core-library@workspace:*":
+  version "3.34.3"
+  resolved "https://registry.yarnpkg.com/@rushstack/node-core-library/-/node-core-library-3.34.3.tgz#a59a1e452dcc79bd4e5f0840b4e9603551668f85"
+  integrity sha512-WNXHEk5/uoZsbrKzGpYUzDDymJvZarRkByab4uS1fbEcTSDFSVB9e0rREzCkU9yDAQlRutbFwiTXLu3LVR5F6w==
  dependencies:
    "@types/node" "10.17.13"
    colors "~1.2.1"
    fs-extra "~7.0.1"
+    import-lazy "~4.0.0"
    jju "~1.4.0"
-    semver "~5.3.0"
+    resolve "~1.17.0"
+    semver "~7.3.0"
    timsort "~0.3.0"
    z-schema "~3.18.3"

-"@rushstack/ts-command-line@4.4.0":
-  version "4.4.0"
-  resolved "https://registry.yarnpkg.com/@rushstack/ts-command-line/-/ts-command-line-4.4.0.tgz#796f24681fdcbd01d463278c9e80a51ea5f73b2b"
-  integrity sha512-AYRICJg9Cwz+IBo1+leG0MtHx2uVScEs5P5ZNW3oocKekN6oLZvM1SNxghB7EXJzmYHnEMvCGhQx0Ll4oEkIyQ==
+"@rushstack/rig-package@workspace:*":
+  version "0.2.4"
+  resolved "https://registry.yarnpkg.com/@rushstack/rig-package/-/rig-package-0.2.4.tgz#259feb6637bedbfdc130d3a188ce85370e048743"
+  integrity sha512-/UXb6N0m0l+5kU4mLmRxyw3we+/w1fesgvfg96xllty5LyQxKDvkscmjlvCU/Yx55WO1tVxN4/7YlNEB2DcHyA==
+  dependencies:
+    "@types/node" "10.17.13"
+    resolve "~1.17.0"
+    strip-json-comments "~3.1.1"
+
+"@rushstack/ts-command-line@workspace:*":
+  version "4.7.3"
+  resolved "https://registry.yarnpkg.com/@rushstack/ts-command-line/-/ts-command-line-4.7.3.tgz#fa72c637d70aa29c201f8f016f7db626f2d23a2c"
+  integrity sha512-8FNrUSbMgKLgRVcsg1STsIC2xAdyes7qJtVwg36hSnBAMZgCCIM+Z36nnxyrnYTS/6qwiXv7fwVaUxXH+SyiAQ==
  dependencies:
    "@types/argparse" "1.0.38"
    argparse "~1.0.9"
    colors "~1.2.1"
+    string-argv "~0.3.1"

 "@samverschueren/stream-to-observable@^0.3.0":
  version "0.3.0"
@ -15350,6 +15364,11 @@ import-lazy@^2.1.0:
  resolved "https://registry.yarnpkg.com/import-lazy/-/import-lazy-2.1.0.tgz#05698e3d45c88e8d7e9d92cb0584e77f096f3e43"
  integrity sha1-BWmOPUXIjo1+nZLLBYTnfwlvPkM=

+import-lazy@~4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/import-lazy/-/import-lazy-4.0.0.tgz#e8eb627483a0a43da3c03f3e35548be5cb0cc153"
+  integrity sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==
+
 import-local@2.0.0, import-local@^2.0.0:
  version "2.0.0"
  resolved "https://registry.yarnpkg.com/import-local/-/import-local-2.0.0.tgz#55070be38a5993cf18ef6db7e961f5bee5c5a09d"
@ -23749,7 +23768,7 @@ resolve@^1.14.2:
  dependencies:
    path-parse "^1.0.6"

-resolve@^1.17.0:
+resolve@^1.17.0, resolve@~1.17.0:
  version "1.17.0"
  resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.17.0.tgz#b25941b54968231cc2d1bb76a79cb7f2c0bf8444"
  integrity sha512-ic+7JYiV8Vi2yzQGFWOkiZD5Z9z7O2Zhm9XMaTxdJExKasieFCr+yXZ/WmXsckHiKl12ar0y6XiXDx3m4RHn1w==
@ -24294,7 +24313,7 @@ semver@7.0.0:
  resolved "https://registry.yarnpkg.com/semver/-/semver-7.0.0.tgz#5f3ca35761e47e05b206c6daff2cf814f0316b8e"
  integrity sha512-+GB6zVA9LWh6zovYQLALHwv5rb2PHGlJi3lfiqIHxR0uuwCgefcOJc59v9fv1w8GbStwxuuqqAjI9NMAOOgq1A==

-semver@7.x, semver@^7.2.1, semver@^7.3.2:
+semver@7.x, semver@^7.2.1, semver@^7.3.2, semver@~7.3.0:
  version "7.3.2"
  resolved "https://registry.yarnpkg.com/semver/-/semver-7.3.2.tgz#604962b052b81ed0786aae84389ffba70ffd3938"
  integrity sha512-OrOb32TeeambH6UrhtShmF7CRDqhL6/5XpPNp2DuRH6+9QLw/orhp72j87v8Qa1ScDkvrrBNpZcDejAirJmfXQ==
@ -25194,7 +25213,7 @@ strict-uri-encode@^1.0.0:
  resolved "https://registry.yarnpkg.com/strict-uri-encode/-/strict-uri-encode-1.1.0.tgz#279b225df1d582b1f54e65addd4352e18faa0713"
  integrity sha1-J5siXfHVgrH1TmWt3UNS4Y+qBxM=

-string-argv@0.3.1:
+string-argv@0.3.1, string-argv@~0.3.1:
  version "0.3.1"
  resolved "https://registry.yarnpkg.com/string-argv/-/string-argv-0.3.1.tgz#95e2fbec0427ae19184935f816d74aaa4c5c19da"
  integrity sha512-a1uQGz7IyVy9YwhqjZIZu1c8JO8dNIe20xBmSS6qu9kv++k3JGzCVmprbNN5Kn+BgzD5E7YYwg1CcjuJMRNsvg==
@ -25461,6 +25480,11 @@ strip-json-comments@~1.0.1:
  resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-1.0.4.tgz#1e15fbcac97d3ee99bf2d73b4c656b082bbafb91"
  integrity sha1-HhX7ysl9Pumb8tc7TGVrCCu6+5E=

+strip-json-comments@~3.1.1:
+  version "3.1.1"
+  resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-3.1.1.tgz#31f1281b3832630434831c310c01cccda8cbe006"
+  integrity sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==
+
 strong-log-transformer@^2.0.0:
  version "2.1.0"
  resolved "https://registry.yarnpkg.com/strong-log-transformer/-/strong-log-transformer-2.1.0.tgz#0f5ed78d325e0421ac6f90f7f10e691d6ae3ae10"
@ -26418,7 +26442,7 @@ typedarray@^0.0.6:
  resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
  integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=

-typescript@3.7.5, typescript@~3.7.2:
+typescript@3.7.5:
  version "3.7.5"
  resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.7.5.tgz#0692e21f65fd4108b9330238aac11dd2e177a1ae"
  integrity sha512-/P5lkRXkWHNAbcJIiHPfRoKqyd7bsyCma1hZNUGfn20qm64T6ZBlrzprymeu918H+mB/0rIg2gGK/BXkhhYgBw==
@ -26428,6 +26452,11 @@ typescript@4.0.2:
  resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.0.2.tgz#7ea7c88777c723c681e33bf7988be5d008d05ac2"
  integrity sha512-e4ERvRV2wb+rRZ/IQeb3jm2VxBsirQLpQhdxplZ2MEzGvDkkMmPglecnNDfSUBivMjP93vRbngYYDQqQ/78bcQ==

+typescript@~3.9.7:
+  version "3.9.7"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-3.9.7.tgz#98d600a5ebdc38f40cb277522f12dc800e9e25fa"
+  integrity sha512-BLbiRkiBzAwsjut4x/dsibSTB6yWpwT5qWmC2OfuCg3GgVQCSgMs4vEctYPhsaGtd0AeuuHMkjZ2h2WG8MSzRw==
+
 typical@^2.6.1:
  version "2.6.1"
  resolved "https://registry.yarnpkg.com/typical/-/typical-2.6.1.tgz#5c080e5d661cbbe38259d2e70a3c7253e873881d"