Merge branch 'develop' into feature-AT-458-scoring_data_customizable

Author: PagoNxt-Trade

docs/getting-started/2-installation.md

@@ -1,6 +1,8 @@
 # Installation
 
-You can install Spectral using [npm](https://www.npmjs.com/):
+You can install Spectral using [npm](https://www.npmjs.com/).
+
+To install the [Spectral CLI client](../guides/2-cli.md), use:
 
 ```bash
 npm install -g @stoplight/spectral-cli
@@ -12,6 +14,18 @@ Or if you are a [Yarn](https://yarnpkg.com/) user:
 yarn global add @stoplight/spectral-cli
 ```
 
+To consume the [Spectral Javascript API](../guides/3-javascript.md), use:
+
+```bash
+npm install -g @stoplight/spectral-core
+```
+
+Or if you are a [Yarn](https://yarnpkg.com/) user:
+
+```bash
+yarn global add @stoplight/spectral-core
+```
+
 ## Executable Binaries
 
 If you don't have Node.js and/or npm/Yarn, use the standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script:

docs/guides/4d-overrides.md

@@ -1,6 +1,6 @@
 ## Overrides
 
-Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or change parts of a rule. Overrides are the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules.
+Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files or change parts of a rule. Overrides are the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules.
 
 Overrides can be used to apply rulesets on:
 
@@ -40,9 +40,9 @@ overrides:
 
 JSON Pointers have a different syntax than JSON Paths used in the `given` component of a rule.
 
-In JSON Pointers, path components are prefixed with a "/" and then concatenated to form the pointer.
+In JSON Pointers, path components are prefixed with a `/` and then concatenated to form the pointer.
 
-Since "/" has a special meaning in JSON pointer, it must be encoded as "~1" when it appears in a component, and "~" must be encoded as "~0".
+Since `/` has a special meaning in JSON pointer, it must be encoded as `~1` when it appears in a component, and `~` must be encoded as `~0`.
 
 You can test JSON Pointer expressions in the [JSON Query online evaluator](https://www.jsonquerytool.com/) by choosing "JSONPointer" as the Transform.
 
@@ -58,9 +58,11 @@ In the event of multiple matches, the order of definition takes place, with the
 
 ### Caveats
 
+#### External Dependencies ($refs)
+
 Overrides are only applied to the _root_ documents. If your documents have any external dependencies ($refs), the overrides won't apply.
 
-**Example:**
+Example:
 
 Given the following 2 YAML documents:
 
@@ -123,3 +125,18 @@ While executing `spectral lint User.yaml` outputs:
 ```
 No results with a severity of 'error' or higher found!
 ```
+
+#### Extended Rulesets (extends)
+
+Overrides aren't supported in other files through [extended rulesets (`extends`)](4b-extends.md). For example, if you create a ruleset file (`rulesetA`) that includes another file (`rulesetB`) through `extends`, overrides are ignored if you apply them to `rulesetB`.
+
+However, you can use JS rulesets to inherit overrides. This example shows how to apply an override in `rulesetB`:
+
+```JavaScript
+import rulesetA from './ruleset';
+
+export default {
+  extends: rulesetA,
+  overrides: rulesetA.overrides,
+};
+```