From c407726a6684eb5f8e36188cb1918e8c56739d75 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Tue, 11 Jul 2023 13:31:52 -0400 Subject: [PATCH] docs: adds vale rules and workflow for running in CI (#2348) * docs: adds vale rules and workflow for running in CI * docs: updates product name from ReDoc to Redoc --- .github/CONTRIBUTING.md | 18 ++- .github/pull_request_template.md | 2 +- .github/styles/Rules/BritishEnglish.yml | 110 +++++++++++++ .github/styles/Rules/FutureTense.yml | 10 ++ .github/styles/Rules/HeaderGerunds.yml | 7 + .../styles/Rules/InclusionGenderCulture.yml | 16 ++ .github/styles/Rules/OxfordComma.yml | 8 + .github/styles/Vocab/Rules/accept.txt | 150 ++++++++++++++++++ .github/styles/Vocab/Rules/reject.txt | 0 .github/workflows/vale.yaml | 16 ++ .vale.ini | 48 ++++++ CHANGELOG.md | 8 +- README.md | 14 +- docs/deployment/html.md | 4 +- docs/deployment/intro.md | 4 +- docs/redoc-vendor-extensions.md | 81 ++++++---- docs/security-definitions-injection.md | 16 +- 17 files changed, 453 insertions(+), 59 deletions(-) create mode 100644 .github/styles/Rules/BritishEnglish.yml create mode 100644 .github/styles/Rules/FutureTense.yml create mode 100644 .github/styles/Rules/HeaderGerunds.yml create mode 100644 .github/styles/Rules/InclusionGenderCulture.yml create mode 100644 .github/styles/Rules/OxfordComma.yml create mode 100644 .github/styles/Vocab/Rules/accept.txt create mode 100644 .github/styles/Vocab/Rules/reject.txt create mode 100644 .github/workflows/vale.yaml create mode 100644 .vale.ini diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index d53188f7..ea300447 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,11 +1,13 @@ -# ReDoc Contributing Guide +# Redoc Contributing Guide -Hi! We're really excited that you are interested in contributing to ReDoc. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines. +Hi! We're really excited that you are interested in contributing to Redoc. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines. -- [Issue Reporting Guidelines](#issue-reporting-guidelines) -- [Pull Request Guidelines](#pull-request-guidelines) -- [Development Setup](#development-setup) -- [Project Structure](#project-structure) +- [Redoc Contributing Guide](#redoc-contributing-guide) + - [Issue Reporting Guidelines](#issue-reporting-guidelines) + - [Pull Request Guidelines](#pull-request-guidelines) + - [Development Setup](#development-setup) + - [Commonly used NPM scripts](#commonly-used-npm-scripts) + - [Project Structure](#project-structure) ## Issue Reporting Guidelines - Before filing a new issue, try to make sure your problem doesn’t already exist. @@ -22,7 +24,7 @@ Before submitting a pull request, please make sure the following is done: ## Development Setup -You will need [Node.js](http://nodejs.org) at `v12.0.0+`. +You need [Node.js](http://nodejs.org) at `v12.0.0+`. After cloning the repo, run: @@ -88,7 +90,7 @@ There are some other scripts available in the `scripts` section of the `package. - **`src/common-elements`**: contains common Styled elements or components used in multiple places - **`src/components`**: contains main visual components - - **`src/services`**: contains different services used by ReDoc including MobX stores + - **`src/services`**: contains different services used by Redoc including MobX stores - **`src/services/models`**: contains classes for OpenAPI entities (e.g. Response, Operations, etc) - **`src/types`**: contains extra typescript typings including OpenAPI doc typings - **`src/utils`**: utility functions diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 4933c4f3..f4486fd0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,7 +2,7 @@ ## Reference -## Testing +## Tests ## Screenshots (optional) diff --git a/.github/styles/Rules/BritishEnglish.yml b/.github/styles/Rules/BritishEnglish.yml new file mode 100644 index 00000000..6c33445f --- /dev/null +++ b/.github/styles/Rules/BritishEnglish.yml @@ -0,0 +1,110 @@ +extends: substitution +message: 'Use the US spelling "%s" instead of British "%s".' +link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words +level: error +ignorecase: true +swap: + aeon: eon + aeroplane: airplane + ageing: aging + aluminium: aluminum + anaemia: anemia + anaesthesia: anesthesia + analyse: analyze + annexe: annex + apologise: apologize + behaviour: behavior + busses: buses + calibre: caliber + cancelled: canceled + cancellation: cancelation + catalogue: catalog + categorise: categorize + categorised: categorized + categorises: categorizes + categorising: categorizing + centre: center + cheque: check + civilisation: civilization + civilise: civilize + colour: color + cosy: cozy + cypher: cipher + dependant: dependent + defence: defense + distil: distill + draught: draft + encyclopaedia: encyclopedia + enquiry: inquiry + enrol: enroll + enrolment: enrollment + enthral: enthrall + expiry: expiration + favourite: favorite + fibre: fiber + fillet: filet + flavour: flavor + furore: furor + fulfil: fulfill + gaol: jail + grey: gray + humour: humor + honour: honor + initialled: initialed + initialling: initialing + instil: instill + jewellery: jewelry + labelling: labeling + labelled: labeled + labour: labor + libellous: libelous + licence: license + likeable: likable + liveable: livable + lustre: luster + manoeuvre: maneuver + marvellous: marvelous + matt: matte + meagre: meager + metre: meter + modelling: modeling + moustache: mustache + neighbour: neighbor + normalise: normalize + offence: offense + organise: organize + organisation: organization + orientated: oriented + paralyse: paralyze + plough: plow + pretence: pretense + programme: program + pyjamas: pajamas + rateable: ratable + realise: realize + recognise: recognize + reconnoitre: reconnoiter + rumour: rumor + sabre: saber + saleable: salable + saltpetre: saltpeter + sceptic: skeptic + sepulchre: sepulcher + signalling: signaling + sizeable: sizable + skilful: skillful + sombre: somber + smoulder: smolder + speciality: specialty + spectre: specter + splendour: splendor + standardise: standardize + standardised: standardized + sulphur: sulfur + theatre: theater + travelled: traveled + traveller: traveler + travelling: traveling + unshakeable: unshakable + wilful: willful + yoghurt: yogurt diff --git a/.github/styles/Rules/FutureTense.yml b/.github/styles/Rules/FutureTense.yml new file mode 100644 index 00000000..1836c0e8 --- /dev/null +++ b/.github/styles/Rules/FutureTense.yml @@ -0,0 +1,10 @@ +extends: existence +message: 'Avoid using future tense: "%s". Use present tense instead.' +link: https://intranet.redoc.ly/contributing/documentation-style-guide/#tone-and-audience +ignorecase: true +level: error +raw: + - "(going to( |\n|[[:punct:]])[a-zA-Z]*|" + - "will( |\n|[[:punct:]])[a-zA-Z]*|" + - "won't( |\n|[[:punct:]])[a-zA-Z]*|" + - "[a-zA-Z]*'ll( |\n|[[:punct:]])[a-zA-Z]*)" diff --git a/.github/styles/Rules/HeaderGerunds.yml b/.github/styles/Rules/HeaderGerunds.yml new file mode 100644 index 00000000..5f593070 --- /dev/null +++ b/.github/styles/Rules/HeaderGerunds.yml @@ -0,0 +1,7 @@ +extends: existence +message: 'Do not start headings with with a gerund (ing word). Use an imperative verb instead.' +link: https://intranet.redoc.ly/contributing/documentation-style-guide/#content-organization +level: error +scope: heading +tokens: + - '^\w*ing.*' diff --git a/.github/styles/Rules/InclusionGenderCulture.yml b/.github/styles/Rules/InclusionGenderCulture.yml new file mode 100644 index 00000000..ea1b653e --- /dev/null +++ b/.github/styles/Rules/InclusionGenderCulture.yml @@ -0,0 +1,16 @@ +extends: substitution +message: 'Use inclusive language. Consider "%s" instead of "%s".' +link: https://intranet.redoc.ly/contributing/documentation-style-guide/#grammar-and-syntax +level: error +ignorecase: true +swap: + he: they + his: their + she: they + hers: their + blacklist(?:ed|ing|s)?: blocklist + whitelist(?:ed|ing|s)?: allowlist + master: primary, main + slave: replica + he/she: they + s/he: they diff --git a/.github/styles/Rules/OxfordComma.yml b/.github/styles/Rules/OxfordComma.yml new file mode 100644 index 00000000..163a5954 --- /dev/null +++ b/.github/styles/Rules/OxfordComma.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Use the Oxford comma in '%s'." +link: https://docs.microsoft.com/en-us/style-guide/punctuation/commas +scope: sentence +level: error +nonword: true +tokens: + - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' diff --git a/.github/styles/Vocab/Rules/accept.txt b/.github/styles/Vocab/Rules/accept.txt new file mode 100644 index 00000000..039d46ed --- /dev/null +++ b/.github/styles/Vocab/Rules/accept.txt @@ -0,0 +1,150 @@ +[Aa]nsible +[Aa]utostart +[Bb]locklist +[Bb]locklists +[Bb]oolean +[Bb]reakpoint +[B]reakpoints +[Cc]ancelation +[Cc]lassloading +[Cc]hargeback +[Cc]hargebacks +[Cc]he +[Cc]rypto +[Cc]ryptocurrency +[Dd]evfile|[Dd]evfiles +[Dd]ownstream +[Dd]ownstreaming +[Ff]actories|[Ff]actory +[Gg]it +[Gg]rafana +[Hh]eatmap +[Hh]elm +[Hh]ostname +[Ii]tem +[Jj]etbrains +[Kk]eycloak +[Ll]iveness +[Ll]ombok +[Ll]oopback +[Mm]aven +[Mm]inikube +[Mm]inishift +[Mm]ixin|[Mm]ixins +[Mm]odularization +[Mm]ulticluster +[Mm]ultihost +[Mm]ultinode +[Mm]ultitenant +[Mm]ultiuser +[Mm]ultizone +[Nn]amespace|[Nn]amespaces +[Nn]etcoredebug[Oo]utput +[Nn]ginx +[Oo]nboarding +[Pp]podman +[Pp]reconfigured +[Rr]eadonly +[Rr]epresentment +[Rr]ollout|[Rr]ollouts +[Rr]untime|[Rr]untimes +[Ss]erializer +[Ss]erverless +[Ss]ubnetwork +[Ss]ubpath|[Ss]ubpaths +[Tt]heia +[Tt]olerations +[Tt]ruststore +[Uu]ninstallation +[Uu]nstaged +[Uu]ntrusted +[Ww]orkspace|[Ww]orkspaces +[Yy]eoman +\.NET +adoc +Antora +API +Apigee +AsciiDoc +AWS|aws +Azure +Bierner +Bitbucket +btn +Btrfs +CentOS +Ceph +Che-Theia +CLI +ConfigMap|ConfigMaps +Ctrl +DaemonSet +Dev Workspace +Developer Perspective +DNS +Docker +Dockerfile +Dotnet +Endevor +endif +GitHub|github +GitLab +Gluster +Gradle +Grafana +GUI +HTTPS|https +I/O +IDE|ide|IDEs +Intelephense +IntelliJ IDEA +Java +Java Lombok +JSON|json +JVM|jvm +kbd +Kubespray +Laravel +Let\'s Encrypt +Mattermost +mebibytes +Microsoft Azure +millicores +Mulesoft +MySQL +Netlify +Node.js +npm +NuGet +OAuth +ocp +OmniSharp +OpenShift +OpenTracing +Operator +OperatorHub +OpenAPI +osd +PHP +PostgreSQL +Quarkus +Rebilly +Redoc +Redocly +Redocly-cli +SCM +Sharding +SonarLint +Spring Boot +SVG +Uber +URI|URIs +URL|url|URLs +Velero +Vercel +Visual Studio Code +vsix +Webview|Webviews +Woopra +YAML|yaml +Zowe diff --git a/.github/styles/Vocab/Rules/reject.txt b/.github/styles/Vocab/Rules/reject.txt new file mode 100644 index 00000000..e69de29b diff --git a/.github/workflows/vale.yaml b/.github/workflows/vale.yaml new file mode 100644 index 00000000..c5220c41 --- /dev/null +++ b/.github/workflows/vale.yaml @@ -0,0 +1,16 @@ +name: Docs lint +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + vale: + name: vale action + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: errata-ai/vale-action@reviewdog + with: + files: '["README.md", "docs"]' + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000..5f29d079 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,48 @@ +# Vale configuration file. +# See: https://docs.errata.ai/vale/config + +# The relative path to the folder containing linting rules (styles). +StylesPath = .github/styles + +# Vocab define the exceptions to use in *all* `BasedOnStyles`. +# spelling-exceptions.txt triggers `Vale.Terms` +# reject.txt triggers `Vale.Avoid` +# See: https://docs.errata.ai/vale/vocab +Vocab = Rules + +# Minimum alert level +# ------------------- +# The minimum alert level in the output (suggestion, warning, or error). +# If integrated into CI, builds fail by default on error-level alerts, unless you run Vale with the --no-exit flag +MinAlertLevel = suggestion + +# IgnoredScopes specifies inline-level HTML tags to ignore. +# These tags may occur in an active scope (unlike SkippedScopes, skipped entirely) but their content still won't raise any alerts. +# Default: ignore `code` and `tt`. +IgnoredScopes = code, tt, img, url, a, body.id +# SkippedScopes specifies block-level HTML tags to ignore. Ignore any content in these scopes. +# Default: ignore `script`, `style`, `pre`, and `figure`. +# For AsciiDoc: by default, listingblock, and literalblock. +SkippedScopes = script, style, pre, figure, code, tt, listingblock, literalblock + +# Rules for matching file types. See: https://docs.errata.ai/vale/scoping + +[formats] +properties = md +mdx = md + +# Rules for .MD, .MDX +[*.{md,mdx}] + +BasedOnStyles = Rules +# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs. +TokenIgnores = (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[) +Vale.Repetition = NO +Vale.SentenceSpacing = NO +Vale.Spelling = NO + +# /End of rules for .MD, .MDX + + +# Process .ini files +[*.ini] diff --git a/CHANGELOG.md b/CHANGELOG.md index f3a9cfb2..37327507 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -159,7 +159,7 @@ * implement configurable minimum characer length to init search ([#1402](https://github.com/Redocly/redoc/issues/1402)) ([0fa08fa](https://github.com/Redocly/redoc/commit/0fa08faab1c176a4bfc5a553e8e8f8b07aca659f)) * support OAS 3.1 unevaluatedProperties ([#1978](https://github.com/Redocly/redoc/issues/1978)) ([0755ac6](https://github.com/Redocly/redoc/commit/0755ac6f04514eb0c08f90afceeda7858206b435)) -* publish dockerhub ([#1971](https://github.com/Redocly/redoc/issues/1971)) ([7e01a0](https://github.com/Redocly/redoc/commit/7e01a0cfe2ad8d06075bfc66ef3860edbef033f8)) +* publish dockerhub ([#1971](https://github.com/Redocly/redoc/issues/1971)) ([7e01a0](https://github.com/Redocly/redoc/commit/7e01a0cfe2ad8d06075bfc66ef3860edbef033f8)) # [2.0.0-rc.67](https://github.com/Redocly/redoc/compare/v2.0.0-rc.66...v2.0.0-rc.67) (2022-04-28) @@ -498,7 +498,7 @@ closes: [#1506](https://github.com/Redocly/redoc/issues/1506), [#1478](https://g ### Bug Fixes -* invalid discriminator dropdown behaviour with enum ([be07197](https://github.com/Redocly/redoc/commit/be07197e6d1e85a3fd3e61189a36b288751c077d)) +* invalid discriminator dropdown behavior with enum ([be07197](https://github.com/Redocly/redoc/commit/be07197e6d1e85a3fd3e61189a36b288751c077d)) @@ -716,7 +716,7 @@ Same as rc.31 by mistake ### Bug Fixes -* empty servers behaviour per OAS spec ([ed1db0c](https://github.com/Redocly/redoc/commit/ed1db0c9027087ae0ae923e390e3e1d638a647ae)), closes [#1151](https://github.com/Redocly/redoc/issues/1151) +* empty servers behavior per OAS spec ([ed1db0c](https://github.com/Redocly/redoc/commit/ed1db0c9027087ae0ae923e390e3e1d638a647ae)), closes [#1151](https://github.com/Redocly/redoc/issues/1151) * fix duplicated content in tags when using md headings ([a260c84](https://github.com/Redocly/redoc/commit/a260c8414c34a259a70a20ebcd20ecbb06c3d250)), closes [#1150](https://github.com/Redocly/redoc/issues/1150) [#1152](https://github.com/Redocly/redoc/issues/1152) * use mobile menu background color value from theme ([#1144](https://github.com/Redocly/redoc/issues/1144)) ([41a9b3c](https://github.com/Redocly/redoc/commit/41a9b3c18228d236d182d3c15c9abc35ae72a0d5)) @@ -1694,7 +1694,7 @@ Complete rewrite also means that this rewrite may introduce issues, but they sho - no more GitHub pages-based CDN. Use [unpkg.com](https://unpkg.com/) to access ReDoc releases -### Known Regression (will be resolved before leaving alpha stage) +### Known Regression (resolved before leaving alpha stage) - `lazyLoading` option not implemented yet - Copying to clipboard of samples not implemented yet - Search not implemented yet diff --git a/README.md b/README.md index 58cf29f6..47d255fb 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ By default Redoc offers a three-panel, responsive layout: ## Live demo -If you want to see how Redoc will render your OpenAPI definition, +If you want to see how Redoc renders your OpenAPI definition, you can try it out online at https://redocly.github.io/redoc/. A version of the Swagger Petstore API is displayed by default. @@ -109,7 +109,7 @@ Refer to the Redocly's documentation for more information on these products: Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**: - particular release, for example `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js - `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js -- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - it will point to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. +- `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - points to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. ## Version Guidance | Redoc Release | OpenAPI Specification | @@ -214,7 +214,7 @@ You can use all of the following options with the standalone version of the 50). In this mode ReDoc shows initial screen ASAP and then renders the rest operations asynchronously while showing progress bar on the top. Check out the [demo](\\redocly.github.io/redoc) for the example.~~ -* `menuToggle` - if true clicking second time on expanded menu item will collapse it, default `true`. +* `menuToggle` - if true, clicking second time on expanded menu item collapses it, default `true`. * `nativeScrollbars` - use native scrollbar for sidemenu instead of perfect-scroll (scrolling performance optimization for big specs). * `onlyRequiredInSamples` - shows only required fields in request samples. * `pathInMiddlePanel` - show path link and HTTP verb in the middle panel instead of the right one. @@ -238,14 +238,14 @@ You can use all of the following options with the standalone version of the Tag Group Object Information about tags group @@ -89,7 +112,7 @@ x-tagGroups: ###### How to use with Redoc -Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by ReDoc. +Use `x-ignoredHeaderParameters` to specify header parameter names which are ignored by Redoc. ###### x-ignoredHeaderParameters example ```yaml @@ -204,7 +227,7 @@ Operation code sample | Field Name | Type | Description | | :---------- | :------: | :----------- | | lang | string | Code sample language. Value should be one of the following [list](https://github.com/github/linguist/blob/master/lib/linguist/popular.yml) | -| label | string? | Code sample label e.g. `Node` or `Python2.7`, _optional_, `lang` will be used by default | +| label | string? | Code sample label, for example `Node` or `Python2.7`, _optional_, `lang` is used by default | | source | string | Code sample source code | @@ -264,7 +287,7 @@ Schemas marked as `x-nullable` are marked in Redoc with the label Nullable ###### How to use with Redoc Redoc uses this vendor extension to solve name-clash issues with the standard `discriminator`. -Value of this field specifies the field which will be used as a extended discriminator. +Value of this field specifies the field which is used as an extended discriminator. Redoc displays definition with selectpicker using which user can select value of the `x-extendedDiscriminator`-marked field. Redoc displays the definition derived from the current (using `allOf`) and has `enum` with only one value which is the same as the selected value of the field specified as `x-extendedDiscriminator`. @@ -347,7 +370,7 @@ Extends the `discriminator` property of the schema object. ###### How to use with Redoc Redoc uses this extension to filter the `discriminator` mappings shown in the selectpicker. -When set to `true`, the selectpicker will only list the the explicitly defined mappings. When `false`, the default behavior is kept, i.e. explicit and implicit mappings will be shown. +When set to `true`, the selectpicker lists only the explicitly defined mappings. When `false`, the default behavior is kept, in other words, explicit and implicit mappings are shown. ###### x-explicitMappingOnly example @@ -366,4 +389,4 @@ Pet: bee: "#/components/schemas/HoneyBee" ``` -Will show in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from the `Pet` class. +Shows in the selectpicker only the items `cat` and `bee`, even though the `Dog` class inherits from the `Pet` class. diff --git a/docs/security-definitions-injection.md b/docs/security-definitions-injection.md index 84071c07..ded59881 100644 --- a/docs/security-definitions-injection.md +++ b/docs/security-definitions-injection.md @@ -1,19 +1,23 @@ # Injection security definitions -You can inject Security Definitions widget into any place of your specification `description`: +You can inject the Security Definitions widget anywhere in your specification `description`: ```markdown ... # Authorization + Some description - + ... ``` -Inject instruction is wrapped into HTML comment so it is **visible only in ReDoc**. It won't be visible e.g. in SwaggerUI. +The inject instruction is wrapped in an HTML comment, +so it is **visible only in Redoc** and not visible, for instance, in the SwaggerUI. # Default behavior -If injection tag is not found in the description it will be appended to the end -of description under `Authentication` header. -If `Authentication` header is already present in the description, Security Definitions won't be inserted and rendered at all. +If the injection tag is not found in the description, it is appended to the end +of description under the `Authentication` header. + +If the `Authentication` header is already present in the description, +Security Definitions are not inserted or rendered.