From a5b38b799aa0251b1414e699e39716cbbdcc8b9e Mon Sep 17 00:00:00 2001 From: Marcus Andersson Date: Tue, 16 Jun 2020 09:33:23 +0200 Subject: [PATCH] Build: scripts to build and measure packages reference docs (#24876) * added script to check docs metrics. * added information link on how to add code comments. * added script for build and measure code comment metrics. * fixed issues according to shellcheck. * Added so we build the metrics if report folder is missing. * added some spacing and a devider. * Added so we can send metrics to grafana. * added shellcheck attribute. * Fixed spelling according to feedback. * see if shellcheck passes. * fixed issue with shellcheck. * Explore/Logs: Fix tooltip display for log graph (#25544) Co-authored-by: Arve Knudsen Co-authored-by: kay delaney <45561153+kaydelaney@users.noreply.github.com> --- package.json | 2 +- ...api_docs.sh => ci-reference-docs-build.sh} | 11 +--- scripts/ci-reference-docs-metrics.sh | 51 ++++++++++++++++ scripts/generate_api_docs.sh | 61 ------------------- yarn.lock | 57 ++++++++++++++--- 5 files changed, 102 insertions(+), 80 deletions(-) rename scripts/{build_api_docs.sh => ci-reference-docs-build.sh} (59%) create mode 100755 scripts/ci-reference-docs-metrics.sh delete mode 100755 scripts/generate_api_docs.sh diff --git a/package.json b/package.json index c7aa5e5d618..4b77d1884de 100644 --- a/package.json +++ b/package.json @@ -69,7 +69,7 @@ "@babel/preset-typescript": "7.8.3", "@emotion/core": "10.0.27", "@grafana/api-documenter": "0.9.3", - "@microsoft/api-extractor": "7.7.8", + "@microsoft/api-extractor": "7.8.2-pr1796.0", "@rtsao/plugin-proposal-class-properties": "7.0.1-patch.1", "@testing-library/react-hooks": "^3.2.1", "@types/angular": "1.6.56", diff --git a/scripts/build_api_docs.sh b/scripts/ci-reference-docs-build.sh similarity index 59% rename from scripts/build_api_docs.sh rename to scripts/ci-reference-docs-build.sh index 2eb5b9a8c9a..ca3532d4cfa 100755 --- a/scripts/build_api_docs.sh +++ b/scripts/ci-reference-docs-build.sh @@ -1,14 +1,7 @@ -#!/usr/bin/env bash +#!/bin/bash # abort if we get any error -set -e - -# always make sure we have a clean workspace -if ! git diff-index --quiet HEAD --; then - echo -e "\033[91mgit workspace is dirty and contains changes\033[0" - echo -e "\033[91mmake sure you have a clean workspace before running this script\033[0m" - exit 1 -fi +set -eo pipefail # building grafana packages echo "building grafana packages..." diff --git a/scripts/ci-reference-docs-metrics.sh b/scripts/ci-reference-docs-metrics.sh new file mode 100755 index 00000000000..3f13f110568 --- /dev/null +++ b/scripts/ci-reference-docs-metrics.sh @@ -0,0 +1,51 @@ +#!/bin/bash + +# 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 "-----------------------------------------------------" +} + +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" +fi + +WARNINGS_COUNT="$(find "$REPORT_PATH" -type f -name \*.log -print0 | xargs -0 grep -o "\[33mWarning:" | wc -l | xargs)" +WARNINGS_COUNT_LIMIT=900 + +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" + 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" \ No newline at end of file diff --git a/scripts/generate_api_docs.sh b/scripts/generate_api_docs.sh deleted file mode 100755 index 5f5a03aecc8..00000000000 --- a/scripts/generate_api_docs.sh +++ /dev/null @@ -1,61 +0,0 @@ -#!/usr/bin/env bash - -# abort if we get any error -set -e - -_current="$(git rev-parse --abbrev-ref HEAD)" -_branch="${_current}-docs" - -if [ "${_current}" == "master" ]; then - echo -e "\033[91myou cannot generate api docs from the master branch\033[0m" - echo "please checkout the release branch" - echo "ex 'git checkout v5.1.x'" - exit 1 -fi - -# always make sure we have a clean workspace -if ! git diff-index --quiet HEAD --; then - echo -e "\033[91mgit workspace is dirty and contains changes\033[0" - echo -e "\033[91mmake sure you have a clean workspace before running this script\033[0m" - exit 1 -fi - -# always make sure to pull latest changes from origin -echo "pulling latest changes from ${_current}" -git pull origin "${_current}" - -# creating new branch for docs update -echo "creating new branch ${_branch}" -git checkout -b "${_branch}" - -# building grafana packages -echo "building grafana packages..." -yarn packages:build - -# extract packages api documentation json -echo "extracting packages documentation data..." -yarn packages:docsExtract - -# generating api documentation markdown -echo "generating markdown from documentation data..." -yarn packages:docsToMarkdown - -echo "updated files:" -git status --porcelain | sed s/^...// - -echo "press [y] to commit documentation update" -read -n 1 confirm - -if [ "${confirm}" == "y" ]; then - git add --all docs/sources/packages_api - git commit -m "docs: updated packages api documentation" - git push origin "${_branch}" - git checkout "${_current}" - echo -e "\033[92mPackages docs successfully updated. Please open a PR from ${_branch} to master.\033[0m" -else - git checkout -- . - git clean -f docs/sources/packages_api - git checkout "${_current}" - git branch -d "${_branch}" - echo -e "\033[91mAbort!\033[0m" -fi diff --git a/yarn.lock b/yarn.lock index 813943d8531..b3a87efe0e5 100644 --- a/yarn.lock +++ b/yarn.lock @@ -4542,15 +4542,23 @@ "@microsoft/node-core-library" "3.19.3" "@microsoft/tsdoc" "0.12.14" -"@microsoft/api-extractor@7.7.8": - version "7.7.8" - resolved "https://registry.yarnpkg.com/@microsoft/api-extractor/-/api-extractor-7.7.8.tgz#19b0bca8a2113d4ded55a270266bc2b802de1a43" - integrity sha512-XNO6Dk6ByfJq24Cn1/j0B0F16ZtwYnEC/sxgB/M0wTphBdBlHjRXZmxofmjirBBj9f7vG4UJ18IOIZRLbhGFPw== +"@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== dependencies: - "@microsoft/api-extractor-model" "7.7.7" - "@microsoft/node-core-library" "3.19.3" - "@microsoft/ts-command-line" "4.3.10" - "@microsoft/tsdoc" "0.12.14" + "@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" @@ -4584,6 +4592,11 @@ resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.12.14.tgz#0e0810a0a174e50e22dfe8edb30599840712f22d" integrity sha512-518yewjSga1jLdiLrcmpMFlaba5P+50b0TWNFUpC+SL9Yzf0kMi57qw+bMl+rQ08cGqH1vLx4eg9YFUbZXgZ0Q== +"@microsoft/tsdoc@0.12.19": + version "0.12.19" + resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.12.19.tgz#2173ccb92469aaf62031fa9499d21b16d07f9b57" + integrity sha512-IpgPxHrNxZiMNUSXqR1l/gePKPkfAmIKoDRP9hp7OwjU29ZR8WCJsOJ8iBKgw0Qk+pFwR+8Y1cy8ImLY6e9m4A== + "@mochajs/json-file-reporter@^1.2.0": version "1.2.0" resolved "https://registry.yarnpkg.com/@mochajs/json-file-reporter/-/json-file-reporter-1.2.0.tgz#036917c90c0291dab5dd4e14323da813108295c8" @@ -4770,6 +4783,28 @@ "@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== + dependencies: + "@types/node" "10.17.13" + colors "~1.2.1" + fs-extra "~7.0.1" + jju "~1.4.0" + semver "~5.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== + dependencies: + "@types/argparse" "1.0.38" + argparse "~1.0.9" + colors "~1.2.1" + "@samverschueren/stream-to-observable@^0.3.0": version "0.3.0" resolved "https://registry.yarnpkg.com/@samverschueren/stream-to-observable/-/stream-to-observable-0.3.0.tgz#ecdf48d532c58ea477acfcab80348424f8d0662f" @@ -5431,6 +5466,11 @@ resolved "https://registry.yarnpkg.com/@types/argparse/-/argparse-1.0.33.tgz#2728669427cdd74a99e53c9f457ca2866a37c52d" integrity sha512-VQgHxyPMTj3hIlq9SY1mctqx+Jj8kpQfoLvDlVSDNOyuYs8JYfkuY3OW/4+dO657yPmNhHpePRx0/Tje5ImNVQ== +"@types/argparse@1.0.38": + version "1.0.38" + resolved "https://registry.yarnpkg.com/@types/argparse/-/argparse-1.0.38.tgz#a81fd8606d481f873a3800c6ebae4f1d768a56a9" + integrity sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA== + "@types/babel-types@*", "@types/babel-types@^7.0.0": version "7.0.7" resolved "https://registry.yarnpkg.com/@types/babel-types/-/babel-types-7.0.7.tgz#667eb1640e8039436028055737d2b9986ee336e3" @@ -10587,7 +10627,6 @@ cyclist@^1.0.1: version "1.0.1" resolved "https://registry.yarnpkg.com/cyclist/-/cyclist-1.0.1.tgz#596e9698fd0c80e12038c2b82d6eb1b35b6224d9" integrity sha1-WW6WmP0MgOEgOMK4LW6xs1tiJNk= - cypress@^4.7.0: version "4.7.0" resolved "https://registry.yarnpkg.com/cypress/-/cypress-4.7.0.tgz#3ea29bddaf9a1faeaa5b8d54b60a84ed1cafa83d"