From ed0bceae3fcbca390bc522e461c842ecd081008a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 14 Jul 2023 08:10:49 -0400 Subject: [PATCH] [editorial] markdownlint in less then 1.5 sec (#193) --- .github/workflows/checks.yml | 2 +- CONTRIBUTING.md | 2 + Makefile | 5 +++ docs/general/general-attributes.md | 2 - docs/general/trace-general.md | 2 + docs/rpc/rpc-metrics.md | 2 - docs/rpc/rpc-spans.md | 1 - gulpfile.js | 60 ++++++++++++++++++++++++++++++ package.json | 10 ++++- 9 files changed, 79 insertions(+), 7 deletions(-) create mode 100644 gulpfile.js diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 9c94e529c7..4ae744dcbe 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -20,7 +20,7 @@ jobs: run: make check-file-and-folder-names-in-docs - name: run markdownlint - run: make markdownlint + run: npx gulp lint-md yamllint: runs-on: ubuntu-latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e69ec11749..158f74ee17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -137,3 +137,5 @@ make misspell-correction - Add `## v{version} ({date})` under `## Unreleased` - Send staging tag as PR for review. - Create a tag `v{version}` on the merged PR and push remote. + +[nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating diff --git a/Makefile b/Makefile index 1375040f7a..f62f8411f6 100644 --- a/Makefile +++ b/Makefile @@ -65,6 +65,11 @@ markdown-toc: .PHONY: markdownlint markdownlint: + @if ! npm ls markdownlint; then npm install; fi + @npx gulp lint-md + +.PHONY: markdownlint-old +markdownlint-old: @if ! npm ls markdownlint; then npm install; fi @for f in $(ALL_DOCS); do \ echo $$f; \ diff --git a/docs/general/general-attributes.md b/docs/general/general-attributes.md index aba52deb49..a8f0b0e79e 100644 --- a/docs/general/general-attributes.md +++ b/docs/general/general-attributes.md @@ -326,8 +326,6 @@ Examples of where the `enduser.id` value is extracted from: | [JavaEE/JakartaEE Servlet] | `javax.servlet.http.HttpServletRequest.getUserPrincipal()` | | [Windows Communication Foundation] | `ServiceSecurityContext.Current.PrimaryIdentity` | -[Authorization]: https://tools.ietf.org/html/rfc7235#section-4.2 -[OAuth 2.0 Access Token]: https://tools.ietf.org/html/rfc6749#section-3.3 [SAML 2.0 Assertion]: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html [HTTP Basic/Digest Authentication]: https://tools.ietf.org/html/rfc2617 [OAuth 2.0 Bearer Token]: https://tools.ietf.org/html/rfc6750 diff --git a/docs/general/trace-general.md b/docs/general/trace-general.md index f19b985c3d..c2294a5978 100644 --- a/docs/general/trace-general.md +++ b/docs/general/trace-general.md @@ -35,3 +35,5 @@ The following semantic conventions for spans are defined: Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own [Resource Semantic Conventions](/docs/resource/README.md). + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index f077245b6c..829faf58da 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -131,8 +131,6 @@ To avoid high cardinality, implementations should prefer the most stable of `ser For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). For server-side spans `server.port` is optional (it describes the port the client is connecting from). -[network.transport]: /docs/general/general-attributes.md#network-attributes - ### Service name On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 9d600b1d58..aae3c5a0d7 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -131,7 +131,6 @@ This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute. Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name. -[network attributes]: /docs/general/general-attributes.md#server-and-client-attributes [`service.name`]: /docs/resource/README.md#service [`peer.service`]: /docs/general/general-attributes.md#general-remote-service-attributes diff --git a/gulpfile.js b/gulpfile.js new file mode 100644 index 0000000000..a42fd496e5 --- /dev/null +++ b/gulpfile.js @@ -0,0 +1,60 @@ +const gulp = require("gulp"); +const through2 = require("through2"); +const markdownlint = require("markdownlint"); +const yaml = require("js-yaml"); +const fs = require("fs"); + +let fileCount = 0, + issueCount = 0; + +function markdownLintFile(file, encoding, callback) { + const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8")); + const options = { + files: [file.path], + config: config, + }; + + markdownlint(options, function (err, result) { + if (err) { + console.error("ERROR occurred while running markdownlint: ", err); + return callback(err); + } + + const _resultString = (result || "").toString(); + // Result is a string with lines of the form: + // + // :\s*: + // + // Strip out any whitespace between the filepath and line number + // so that tools can jump directly to the line. + const resultString = _resultString + .split("\n") + .map((line) => line.replace(/^([^:]+):\s*(\d+):(.*)/, "$1:$2:$3")) + .join("\n"); + if (resultString) { + console.log(resultString); + issueCount++; + } + fileCount++; + callback(null, file); + }); +} + +function lintMarkdown() { + const markdownFiles = ["**/*.md", "!**/node_modules/**", "!**/.github/**"]; + + return gulp + .src(markdownFiles) + .pipe(through2.obj(markdownLintFile)) + .on("end", () => { + console.log( + `Processed ${fileCount} file${ + fileCount == 1 ? "" : "s" + }, ${issueCount} had issues.`, + ); + }); +} + +lintMarkdown.description = `Run markdownlint on all '*.md' files.`; + +gulp.task("lint-md", lintMarkdown); diff --git a/package.json b/package.json index 2cd780144d..0bbc27cb39 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,15 @@ { "devDependencies": { + "gulp": "^4.0.2", + "js-yaml": "^4.1.0", "markdown-link-check": "3.10.3", "markdown-toc": "^1.2.0", - "markdownlint-cli": "0.31.0" + "markdownlint": "^0.29.0", + "markdownlint-cli": "0.31.0", + "prettier": "^3.0.0", + "through2": "^4.0.2" + }, + "prettier": { + "proseWrap": "preserve" } }