Skip to content

Commit 54b63ee

Browse files
nastasha-solomonnastasha-solomon
authored
Merge branch 'main' into add-azure-and-gcp-ml-jobs
2 parents 0b2bd92 + 6bf5189 commit 54b63ee

File tree

8 files changed

+136
-124
lines changed

8 files changed

+136
-124
lines changed

‎contribute-docs/images/vale-ide.png‎

88.6 KB
Loading

‎contribute-docs/images/vale-sticky-comment.png‎

87.6 KB
Loading

‎contribute-docs/vale-linter.md‎

Lines changed: 94 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,40 @@
11
---
2-
navigation_title: Vale linter
2+
navigation_title: Vale style checker
33
---
44

55
# Elastic style guide for Vale
66

7-
[Vale](https://github.com/errata-ai/vale) is an open source prose linter that checks the content of documents in several formats against style guide rules. The goal of a prose linter is automating style guide checks in docs-as-code environments, so that style issues are detected before deploy or while editing documentation in a code editor.
7+
[Vale](https://github.com/errata-ai/vale) is a prose linter that checks documentation in Markdown format against the [Elastic style guide](/contribute-docs/style-guide/index.md). The documentation is checked when you commit changes to a pull request.
88

9-
The Elastic Vale package contains a set of linting rules based on the Elastic style guide and recommendations.
9+
Follow the instructions on this page to:
1010

11-
## Get started
11+
- [Use the Vale action for GitHub](/contribute-docs/vale-linter.md#vale-checks-in-pull-requests) to check for style issues when you commit changes to a pull request.
12+
- [Use the Vale linter in your IDE](/contribute-docs/vale-linter.md#use-the-vale-linter-locally) to check for style issues while writing documentation.
1213

13-
Run these commands to install the Elastic style guide locally:
14+
## Vale checks in pull requests [vale-checks-in-pull-requests]
15+
16+
The Vale action for GitHub runs Vale checks on pull requests that include documentation changes. The action reports any style issues found in modified lines in the form of a sticky comment.
17+
18+
:::{image} ./images/vale-sticky-comment.png
19+
:alt: Vale comment in pull request
20+
:screenshot:
21+
:width: 85%
22+
:::
23+
24+
Issues are reported in the form of errors, warnings, and suggestions. You can expand each category to browse the specific issues. The report updates every time you commit changes.
25+
26+
:::{important}
27+
Make an effort to fix all warnings and suggestions reported by the Vale linter. This helps ensure your docs read well and are easier to understand.
28+
:::
29+
30+
## Use the Vale linter locally [use-the-vale-linter-locally]
31+
32+
You can use the Vale linter locally to check for style issues while writing documentation.
33+
34+
::::::{stepper}
35+
36+
:::::{step} Install Vale and the Elastic style
37+
Run these commands to install the Elastic style guide locally. If Vale isn't installed, the commands install it for you or suggest how to do it.
1438

1539
::::{tab-set}
1640

@@ -40,123 +64,81 @@ powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
4064
:::
4165
::::
4266

43-
:::{warning}
44-
The installation script might overwrite your existing global Vale configuration. Install the style manually if you're using styles other than Elastic.
67+
:::{tip}
68+
To update the Elastic style guide to the latest rules, rerun the installation script.
4569
:::
70+
:::::
4671

47-
### Install the Visual Studio Code extension
48-
49-
Install the [Vale VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) extension to view Vale checks when saving a document. The extension is also available for other editors that support the Open VSX Registry.
50-
51-
## Add the Vale action to your repo
52-
53-
Add the Elastic Vale linter to your repository's CI/CD pipeline using a two-workflow setup that supports fork PRs:
54-
55-
```yaml
56-
# .github/workflows/vale-lint.yml
57-
name: Vale Documentation Linting
58-
59-
on:
60-
pull_request:
61-
paths:
62-
- '**.md'
63-
- '**.adoc'
64-
65-
permissions:
66-
contents: read
67-
68-
jobs:
69-
vale:
70-
runs-on: ubuntu-latest
71-
steps:
72-
- name: Checkout
73-
uses: actions/checkout@v5
74-
with:
75-
fetch-depth: 0
76-
77-
- name: Run Vale Linter
78-
uses: elastic/vale-rules/lint@main
79-
```
80-
81-
```yaml
82-
# .github/workflows/vale-report.yml
83-
name: Vale Report
84-
85-
on:
86-
workflow_run:
87-
workflows: ["Vale Documentation Linting"]
88-
types:
89-
- completed
90-
91-
permissions:
92-
pull-requests: read
93-
94-
jobs:
95-
report:
96-
runs-on: ubuntu-latest
97-
if: github.event.workflow_run.event == 'pull_request'
98-
permissions:
99-
pull-requests: write
100-
101-
steps:
102-
- name: Post Vale Results
103-
uses: elastic/vale-rules/report@main
104-
with:
105-
github_token: ${{ secrets.GITHUB_TOKEN }}
106-
```
107-
108-
For detailed documentation and examples, refer to [ACTION_USAGE.md](https://github.com/elastic/vale-rules/blob/main/ACTION_USAGE.md).
109-
110-
## Exclude content from linting
111-
112-
You can use HTML comments in your Markdown files to control Vale's behavior for specific sections of content. This is useful when you need to temporarily turn off checks or exclude certain content from linting.
113-
114-
### Turn off all Vale checks
115-
116-
To exclude a section of content from linting, wrap it with `vale off` and `vale on` comments:
117-
118-
```markdown
119-
<!-- vale off -->
120-
121-
This entire section will be ignored by Vale.
122-
123-
<!-- vale on -->
124-
```
125-
126-
### Turn off a specific rule
127-
128-
To turn off a specific Elastic style rule for a section, use the rule name with `= NO` and `= YES` to turn it back on:
72+
:::::{step} Install the IDE extension
73+
Install the [Vale VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) extension. The extension is also available for other editors that support the Open VSX Registry, like Cursor.
74+
:::::
12975

130-
```markdown
131-
<!-- vale Elastic.RuleName = NO -->
76+
:::::{step} Open any Markdown file
77+
The extension automatically runs Vale checks when you save a document. Issues are reported both in the Problems tab and in the editor itself.
13278

133-
This content will ignore only the specified rule.
134-
135-
<!-- vale Elastic.RuleName = YES -->
136-
```
137-
138-
For example, to turn off the `Elastic.WordChoice` rule:
139-
140-
```markdown
141-
<!-- vale Elastic.WordChoice = NO -->
142-
143-
This section can contain mispellings without triggering warnings.
144-
145-
<!-- vale Elastic.WordChoice = YES -->
146-
```
79+
:::{image} ./images/vale-ide.png
80+
:alt: Vale comment in pull request
81+
:screenshot:
82+
:width: 100%
83+
:::
84+
:::::
85+
86+
::::::
87+
88+
## Style rules reference [elastic-style-rules-reference]
89+
90+
The following table lists all the rules included in the [Elastic Vale style package](https://github.com/elastic/vale-rules/tree/main/styles/Elastic):
91+
92+
| Rule | Description |
93+
|-------------|-------------|
94+
| [Accessibility](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Accessibility.yml) | Flags ableist language that defines people by their disability. Refer to [Avoid violent, offensive, ableist terminology](./style-guide/accessibility.md#avoid-violent-offensive-ableist-terminology). |
95+
| [Acronyms](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Acronyms.yml) | Checks that acronyms are defined before being used (unless they're common exceptions). Refer to [Abbreviations and acronyms](./style-guide/grammar-spelling.md#abbreviations-and-acronyms). |
96+
| [Articles](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Articles.yml) | Ensures correct article usage ("a" vs "an") based on pronunciation, not spelling. Refer to [Using the right article](./style-guide/grammar-spelling.md#using-the-right-article). |
97+
| [BritishSpellings](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/BritishSpellings.yml) | Suggests American English spellings instead of British English variants. Refer to [American English](./style-guide/grammar-spelling.md#american-english). |
98+
| [Capitalization](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Capitalization.yml) | Checks that headings use sentence-style capitalization. Refer to [Capitalization](./style-guide/grammar-spelling.md#capitalization). |
99+
| [ConflictMarkers](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/ConflictMarkers.yml) | Detects Git merge conflict markers in source code. |
100+
| [DeviceAgnosticism](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/DeviceAgnosticism.yml) | Suggests device-agnostic language (for example, "select" instead of "tap"). Refer to [Use device-agnostic language](./style-guide/accessibility.md#accessibility-guidelines). |
101+
| [Dimensions](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Dimensions.yml) | Suggests using "MxN" format instead of "M X N" for dimensions. Refer to [Dimensions](./style-guide/formatting.md#dimensions). |
102+
| [DontUse](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/DontUse.yml) | Flags words and phrases that shouldn't be used (for example, "please", "just", "aka"). Refer to [Word choice](./style-guide/word-choice.md). |
103+
| [Ellipses](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Ellipses.yml) | Discourages the use of ellipses. Refer to [Write like a minimalist](./style-guide/voice-tone.md#write-like-a-minimalist). |
104+
| [EmDashes](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/EmDashes.yml) | Checks that em dashes don't have spaces before or after. Refer to [Em dashes](./style-guide/grammar-spelling.md#em-dashes). |
105+
| [EndPuntuaction](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/EndPuntuaction.yml) | Flags headings that end with punctuation. Refer to [Capitalization](./style-guide/grammar-spelling.md#capitalization). |
106+
| [Exclamation](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Exclamation.yml) | Encourages sparing use of exclamation points. Refer to [Tone](./style-guide/voice-tone.md#tone). |
107+
| [FirstPerson](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/FirstPerson.yml) | Discourages first-person pronouns (I, me, my, mine). Refer to [Use singular first-person pronouns sparingly](./style-guide/grammar-spelling.md#use-singular-first-person-pronouns-sparingly-i-me-my-mine). |
108+
| [FutureTense](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/FutureTense.yml) | Encourages writing in present tense instead of future tense. Refer to [Verb tense](./style-guide/grammar-spelling.md#verb-tense). |
109+
| [Gender](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Gender.yml) | Flags gender-specific compound pronouns like "he/she" or "s/he". Refer to [Use gender-neutral language](./style-guide/accessibility.md#use-gender-neutral-language). |
110+
| [GenderBias](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/GenderBias.yml) | Suggests gender-neutral alternatives for gendered terms. Refer to [Use gender-neutral language](./style-guide/accessibility.md#use-gender-neutral-language). |
111+
| [HeadingColons](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/HeadingColons.yml) | Checks that text after colons in headings is capitalized. Refer to [Colons](./style-guide/grammar-spelling.md#colons). |
112+
| [Latinisms](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Latinisms.yml) | Suggests plain English alternatives to Latin terms (for example, "for example" instead of "e.g."). Refer to [Latin abbreviations](./style-guide/grammar-spelling.md#latin-abbreviations). |
113+
| [MeaningfulCTAs](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/MeaningfulCTAs.yml) | Flags non-descriptive link text like "click here". Refer to [Use meaningful link text](./style-guide/accessibility.md#accessibility-guidelines). |
114+
| [Negations](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Negations.yml) | Suggests rephrasing negative constructions to positive ones. Refer to [Write for an international audience](./style-guide/accessibility.md#write-for-an-international-audience). |
115+
| [OxfordComma](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/OxfordComma.yml) | Enforces the use of the Oxford comma in lists. Refer to [Commas](./style-guide/grammar-spelling.md#commas). |
116+
| [PluralAbbreviations](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/PluralAbbreviations.yml) | Flags apostrophes in plural abbreviations (use "APIs" instead of "API's"). Refer to [Making abbreviations plural](./style-guide/grammar-spelling.md#making-abbreviations-plural). |
117+
| [QuotesPunctuation](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/QuotesPunctuation.yml) | Ensures punctuation is placed outside quotation marks. Refer to [Punctuation](./style-guide/grammar-spelling.md#punctuation). |
118+
| [Repetition](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Repetition.yml) | Detects repeated words. Refer to [Write like a minimalist](./style-guide/voice-tone.md#write-like-a-minimalist). |
119+
| [Semicolons](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Semicolons.yml) | Encourages judicious use of semicolons. Refer to [Semicolons](./style-guide/grammar-spelling.md#semicolons). |
120+
| [Versions](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Versions.yml) | Suggests "later" or "earlier" instead of "newer", "older", "higher", or "lower" for versions. |
121+
| [WordChoice](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/WordChoice.yml) | Suggests preferred word choices (for example, "stop" instead of "abort", "allowlist" instead of "whitelist"). Refer to [Word choice](./style-guide/word-choice.md). |
122+
| [Wordiness](https://github.com/elastic/vale-rules/blob/main/styles/Elastic/Wordiness.yml) | Suggests concise alternatives to wordy phrases. Refer to [Write like a minimalist](./style-guide/voice-tone.md#write-like-a-minimalist). |
123+
124+
## Vocabularies [elastic-vocabularies]
125+
126+
The Elastic Vale style uses [Vale vocabularies](https://vale.sh/docs/keys/vocab) to recognize product and feature names. Vocabularies help Vale avoid false positives when checking capitalization and spelling rules.
127+
128+
The Elastic style includes these vocabularies:
129+
130+
- [**ElasticTerms**](https://github.com/elastic/vale-rules/blob/main/styles/config/vocabularies/ElasticTerms/accept.txt): Contains Elastic product and feature names (for example, Elasticsearch, Kibana, Elastic Agent).
131+
- [**ThirdPartyProducts**](https://github.com/elastic/vale-rules/blob/main/styles/config/vocabularies/ThirdPartyProducts/accept.txt): Contains non-Elastic product names (for example, Kubernetes, AWS, Docker).
147132

148133
:::{tip}
149-
You can find the exact rule names in the [Elastic Vale rules repository](https://github.com/elastic/vale-rules/tree/main/styles/Elastic). Each rule is defined in a separate `.yml` file, and the filename (without the extension) is the rule name you use in comments.
134+
If Vale incorrectly flags a product or feature name, suggest adding it to the appropriate vocabulary by creating a pull request or issue in the [Elastic Vale rules repository](https://github.com/elastic/vale-rules).
150135
:::
151136

152-
For more information about comment-based configuration, refer to the [Vale Markdown documentation](https://vale.sh/docs/formats/markdown#comments).
137+
## Report issues or suggest improvements [report-issues-or-suggest-improvements]
153138

154-
## Update the style guide
139+
You can report issues or suggest improvements to the Elastic style guide by creating an issue in the [Elastic Vale rules repository](https://github.com/elastic/vale-rules/issues).
155140

156-
To update the Elastic style guide to the latest rules, rerun the installation script.
157-
158-
## Resources
141+
## Additional resources [additional-resources]
159142

160143
- [Vale's official documentation](https://vale.sh/docs/vale-cli/overview/)
161144
- [Elastic Vale rules repository](https://github.com/elastic/vale-rules)
162-

‎contribute-docs/vscode-extension.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
2-
navigation_title: Elastic Docs Utilities extension
2+
navigation_title: Elastic Docs Utilities
33
---
44

5-
# Elastic Docs Utilities extension
5+
# Elastic Docs Utilities
66

77
The Elastic Docs Utilities extension for Visual Studio Code and compatible IDEs provides autocompletion for Elastic Docs' Markdown, along with other features for authoring Elastic documentation.
88

@@ -17,11 +17,11 @@ The Elastic Docs Utilities extension for Visual Studio Code and compatible IDEs
1717
To install the extension:
1818

1919
1. Open the Visual Studio Marketplace or the **Extensions** view in your editor.
20-
2. Search for `Elastic Docs Utilities` or go to the [extension page](https://marketplace.visualstudio.com/items?itemName=elastic.elastic-docs-v3-utilities).
20+
2. Search for `Elastic Docs Utilities`.
2121
3. Select **Install** to add the extension to your editor.
2222

2323
:::{tip}
24-
The extension is also available for other editors that support the Open VSX Registry.
24+
The extension is also available for editors that support the Open VSX Registry, like Cursor.
2525
:::
2626

2727
## Availability

‎deploy-manage/production-guidance/optimize-performance/approximate-knn-search.md‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -61,19 +61,32 @@ Here are estimates for different element types and quantization levels:
6161
| `float` | none | `num_vectors * num_dimensions * 4` |
6262
| `float` | `int8` | `num_vectors * (num_dimensions + 4)` |
6363
| `float` | `int4` | `num_vectors * (num_dimensions/2 + 4)` |
64-
| `float ` | `bbq` | `num_vectors * (num_dimensions/8 + 14)` |
64+
| `float` | `bbq` | `num_vectors * (num_dimensions/8 + 14)` |
65+
| `bfloat16` | none | `num_vectors * num_dimensions * 2` |
66+
| `bfloat16` | `int8` | `num_vectors * (num_dimensions + 4)` |
67+
| `bfloat16` | `int4` | `num_vectors * (num_dimensions/2 + 4)` |
68+
| `bfloat16` | `bbq` | `num_vectors * (num_dimensions/8 + 14)` |
6569
| `byte` | none | `num_vectors * num_dimensions` |
6670
| `bit` | none | `num_vectors * (num_dimensions/8)` |
6771

6872
If you're using HNSW, the graph must also be in memory. To estimate the required bytes, use the following formula below. The default value for the HNSW `m` parameter is `16`.
6973

74+
For `element_type: float`:
7075
```{math}
7176
\begin{align*}
7277
estimated\ bytes &= num\_vectors \times 4 \times m \\
7378
&= num\_vectors \times 4 \times 16
7479
\end{align*}
7580
```
7681

82+
For `element_type: bfloat16`:
83+
```{math}
84+
\begin{align*}
85+
estimated\ bytes &= num\_vectors \times 2 \times m \\
86+
&= num\_vectors \times 2 \times 16
87+
\end{align*}
88+
```
89+
7790
If you're using DiskBBQ, a fraction of the clusters and centroids need to be in memory. When doing this estimation, it makes more sense to include both the index structure and the quantized vectors together as the structures are dependent. To estimate the total bytes, first compute the number of clusters, then compute the cost of the centroids plus the cost of the quantized vectors within the clusters to get the total estimated bytes. The default value for the number of `vectors_per_cluster` is `384`.
7891

7992
```{math}
@@ -195,13 +208,11 @@ You can check the current value in `KiB` using `lsblk -o NAME,RA,MOUNTPOINT,TYPE
195208
::::
196209

197210

198-
## Use Direct IO when the vector data does not fit in RAM
211+
## Use on-disk rescoring when the vector data does not fit in RAM
199212
```{applies_to}
200-
stack: preview 9.1
213+
stack: preview 9.3
201214
serverless: unavailable
202215
```
203-
If your indices are of type `bbq_hnsw` and your nodes don't have enough off-heap RAM to store all vector data in memory, you may see very high query latencies. Vector data includes the HNSW graph, quantized vectors, and raw float32 vectors.
204-
205-
In these scenarios, direct IO can significantly reduce query latency. Enable it by setting the JVM option `vector.rescoring.directio=true` on all vector search nodes in your cluster.
216+
If you use quantized indices and your nodes don't have enough off-heap RAM to store all vector data in memory, then you might experience high query latencies. Vector data includes the HNSW graph, quantized vectors, and raw float vectors.
206217

207-
Only use this option if you're experiencing very high query latencies on indices of type `bbq_hnsw`. Otherwise, enabling direct IO may increase your query latencies.
218+
In these scenarios, on-disk rescoring can significantly reduce query latency. Enable it by setting the `on_disk_rescore: true` option on your vector indices. Your data must be re-indexed or force-merged to use the new setting in subsequent searches.

‎solutions/observability/apm/data-streams.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ Traces
3535
: Traces are comprised of [spans and transactions](/solutions/observability/apm/data-types.md). Traces are stored in the following data streams:
3636

3737
* Application traces: `traces-apm-<namespace>`
38+
* Sampled application traces: `traces-apm.sampled-<namespace>`
3839
* RUM and iOS agent application traces: `traces-apm.rum-<namespace>`
3940

4041
Metrics

0 commit comments

Comments
 (0)