Skip to content

Commit 85f73f0

Browse files
poliorceticspoliorcetics
committed
highlights: document them all and add a CI check to ensure language higlights don't add undocumented ones
1 parent e167969 commit 85f73f0

File tree

6 files changed

+641
-162
lines changed

6 files changed

+641
-162
lines changed

‎.github/workflows/build.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,10 +108,12 @@ jobs:
108108
- name: Generate docs
109109
run: cargo xtask docgen
110110

111+
- name: All highlight queries keys are statically known
112+
run: cargo xtask theme-keys-check
113+
111114
- name: Check uncommitted documentation changes
112115
run: |
113116
git diff
114117
git diff-files --quiet \
115118
|| (echo "Run 'cargo xtask docgen', commit the changes and push again" \
116119
&& exit 1)
117-

‎book/src/generated/theme-table.md‎

Lines changed: 193 additions & 0 deletions
Large diffs are not rendered by default.

‎book/src/themes.md‎

Lines changed: 2 additions & 156 deletions
Original file line numberDiff line numberDiff line change
@@ -136,166 +136,12 @@ We use a similar set of scopes as
136136
[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also
137137
[TextMate](https://macromates.com/manual/en/language_grammars) scopes.
138138

139-
- `attribute` - Class attributes, html tag attributes
140-
141-
- `type` - Types
142-
- `builtin` - Primitive types provided by the language (`int`, `usize`)
143-
- `constructor`
144-
145-
- `constant` (TODO: constant.other.placeholder for %v)
146-
- `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)
147-
- `boolean`
148-
- `character`
149-
- `escape`
150-
- `numeric` (numbers)
151-
- `integer`
152-
- `float`
153-
154-
- `string` (TODO: string.quoted.{single, double}, string.raw/.unquoted)?
155-
- `regexp` - Regular expressions
156-
- `special`
157-
- `path`
158-
- `url`
159-
- `symbol` - Erlang/Elixir atoms, Ruby symbols, Clojure keywords
160-
161-
- `comment` - Code comments
162-
- `line` - Single line comments (`//`)
163-
- `block` - Block comments (e.g. (`/* */`)
164-
- `documentation` - Documentation comments (e.g. `///` in Rust)
165-
166-
- `variable` - Variables
167-
- `builtin` - Reserved language variables (`self`, `this`, `super`, etc)
168-
- `parameter` - Function parameters
169-
- `other`
170-
- `member` - Fields of composite data types (e.g. structs, unions)
171-
172-
- `label`
173-
174-
- `punctuation`
175-
- `delimiter` - Commas, colons
176-
- `bracket` - Parentheses, angle brackets, etc.
177-
- `special` - String interpolation brackets.
178-
179-
- `keyword`
180-
- `control`
181-
- `conditional` - `if`, `else`
182-
- `repeat` - `for`, `while`, `loop`
183-
- `import` - `import`, `export`
184-
- `return`
185-
- `exception`
186-
- `operator` - `or`, `in`
187-
- `directive` - Preprocessor directives (`#if` in C)
188-
- `function` - `fn`, `func`
189-
- `storage` - Keywords describing how things are stored
190-
- `type` - The type of something, `class`, `function`, `var`, `let`, etc.
191-
- `modifier` - Storage modifiers like `static`, `mut`, `const`, `ref`, etc.
192-
193-
- `operator` - `||`, `+=`, `>`
194-
195-
- `function`
196-
- `builtin`
197-
- `method`
198-
- `macro`
199-
- `special` (preprocessor in C)
200-
201-
- `tag` - Tags (e.g. `<body>` in HTML)
202-
203-
- `namespace`
204-
205-
- `markup`
206-
- `heading`
207-
- `marker`
208-
- `1`, `2`, `3`, `4`, `5`, `6` - heading text for h1 through h6
209-
- `list`
210-
- `unnumbered`
211-
- `numbered`
212-
- `bold`
213-
- `italic`
214-
- `link`
215-
- `url` - urls pointed to by links
216-
- `label` - non-url link references
217-
- `text` - url and image descriptions in links
218-
- `quote`
219-
- `raw`
220-
- `inline`
221-
- `block`
222-
223-
- `diff` - version control changes
224-
- `plus` - additions
225-
- `minus` - deletions
226-
- `delta` - modifications
227-
- `moved` - renamed or moved files/changes
228-
229-
#### Interface
230-
231-
These scopes are used for theming the editor interface.
232-
233-
- `markup`
234-
- `normal`
235-
- `completion` - for completion doc popup ui
236-
- `hover` - for hover popup ui
237-
- `heading`
238-
- `completion` - for completion doc popup ui
239-
- `hover` - for hover popup ui
240-
- `raw`
241-
- `inline`
242-
- `completion` - for completion doc popup ui
243-
- `hover` - for hover popup ui
244-
245-
246-
| Key | Notes |
247-
| --- | --- |
248-
| `ui.background` | |
249-
| `ui.background.separator` | Picker separator below input line |
250-
| `ui.cursor` | |
251-
| `ui.cursor.insert` | |
252-
| `ui.cursor.select` | |
253-
| `ui.cursor.match` | Matching bracket etc. |
254-
| `ui.cursor.primary` | Cursor with primary selection |
255-
| `ui.gutter` | Gutter |
256-
| `ui.gutter.selected` | Gutter for the line the cursor is on |
257-
| `ui.linenr` | Line numbers |
258-
| `ui.linenr.selected` | Line number for the line the cursor is on |
259-
| `ui.statusline` | Statusline |
260-
| `ui.statusline.inactive` | Statusline (unfocused document) |
261-
| `ui.statusline.normal` | Statusline mode during normal mode ([only if `editor.color-modes` is enabled][editor-section]) |
262-
| `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |
263-
| `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |
264-
| `ui.statusline.separator` | Separator character in statusline |
265-
| `ui.popup` | Documentation popups (e.g Space + k) |
266-
| `ui.popup.info` | Prompt for multiple key options |
267-
| `ui.window` | Border lines separating splits |
268-
| `ui.help` | Description box for commands |
269-
| `ui.text` | Command prompts, popup text, etc. |
270-
| `ui.text.focus` | |
271-
| `ui.text.inactive` | Same as `ui.text` but when the text is inactive (e.g. suggestions) |
272-
| `ui.text.info` | The key: command text in `ui.popup.info` boxes |
273-
| `ui.virtual.ruler` | Ruler columns (see the [`editor.rulers` config][editor-section]) |
274-
| `ui.virtual.whitespace` | Visible whitespace characters |
275-
| `ui.virtual.indent-guide` | Vertical indent width guides |
276-
| `ui.menu` | Code and command completion menus |
277-
| `ui.menu.selected` | Selected autocomplete item |
278-
| `ui.menu.scroll` | `fg` sets thumb color, `bg` sets track color of scrollbar |
279-
| `ui.selection` | For selections in the editing area |
280-
| `ui.selection.primary` | |
281-
| `ui.cursorline.primary` | The line of the primary cursor ([if cursorline is enabled][editor-section]) |
282-
| `ui.cursorline.secondary` | The lines of any other cursors ([if cursorline is enabled][editor-section]) |
283-
| `ui.cursorcolumn.primary` | The column of the primary cursor ([if cursorcolumn is enabled][editor-section]) |
284-
| `ui.cursorcolumn.secondary` | The columns of any other cursors ([if cursorcolumn is enabled][editor-section]) |
285-
| `warning` | Diagnostics warning (gutter) |
286-
| `error` | Diagnostics error (gutter) |
287-
| `info` | Diagnostics info (gutter) |
288-
| `hint` | Diagnostics hint (gutter) |
289-
| `diagnostic` | Diagnostics fallback style (editing area) |
290-
| `diagnostic.hint` | Diagnostics hint (editing area) |
291-
| `diagnostic.info` | Diagnostics info (editing area) |
292-
| `diagnostic.warning` | Diagnostics warning (editing area) |
293-
| `diagnostic.error` | Diagnostics error (editing area) |
139+
**Note**: not all language keys are applicable to all languages, you can have a look at the `runtime/queries/*/highlights.scm` files to see what is defined or not for your language of choice.
294140

295141
You can check compliance to spec with
296142

297143
```shell
298144
cargo xtask themelint onedark # replace onedark with <name>
299145
```
300146

301-
[editor-section]: ./configuration.md#editor-section
147+
{{#include generated/theme-table.md}}

‎xtask/src/docgen.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ use std::fs;
88

99
pub const TYPABLE_COMMANDS_MD_OUTPUT: &str = "typable-cmd.md";
1010
pub const LANG_SUPPORT_MD_OUTPUT: &str = "lang-support.md";
11+
pub const THEME_TABLE_MD_OUTPUT: &str = "theme-table.md";
1112

1213
fn md_table_heading(cols: &[String]) -> String {
1314
let mut header = String::new();

‎xtask/src/main.rs‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,29 @@ mod docgen;
22
mod helpers;
33
mod path;
44
mod querycheck;
5+
mod themekeyscheck;
56
mod themelint;
67

78
use std::{env, error::Error};
89

910
type DynError = Box<dyn Error>;
1011

1112
pub mod tasks {
12-
use crate::docgen::{lang_features, typable_commands, write};
13-
use crate::docgen::{LANG_SUPPORT_MD_OUTPUT, TYPABLE_COMMANDS_MD_OUTPUT};
14-
use crate::querycheck::query_check;
13+
use crate::docgen::{
14+
lang_features, typable_commands, write, LANG_SUPPORT_MD_OUTPUT, THEME_TABLE_MD_OUTPUT,
15+
TYPABLE_COMMANDS_MD_OUTPUT,
16+
};
17+
use crate::themekeyscheck::theme_keys_doc;
1518
use crate::themelint::{lint, lint_all};
1619
use crate::DynError;
20+
// Reexports for direct usage
21+
pub use crate::querycheck::query_check;
22+
pub use crate::themekeyscheck::theme_keys_check;
1723

1824
pub fn docgen() -> Result<(), DynError> {
1925
write(TYPABLE_COMMANDS_MD_OUTPUT, &typable_commands()?);
2026
write(LANG_SUPPORT_MD_OUTPUT, &lang_features()?);
27+
write(THEME_TABLE_MD_OUTPUT, &theme_keys_doc());
2128
Ok(())
2229
}
2330

@@ -36,11 +43,11 @@ pub mod tasks {
3643
println!(
3744
"
3845
Usage: Run with `cargo xtask <task>`, eg. `cargo xtask docgen`.
39-
4046
Tasks:
4147
docgen: Generate files to be included in the mdbook output.
4248
themelint <theme>: Report errors for <theme>, or all themes if no theme is specified.
4349
query-check: Check that tree-sitter queries are valid.
50+
theme-keys-check: Check that all highlight queries are documented.
4451
"
4552
);
4653
}
@@ -53,7 +60,8 @@ fn main() -> Result<(), DynError> {
5360
Some(t) => match t.as_str() {
5461
"docgen" => tasks::docgen()?,
5562
"themelint" => tasks::themelint(env::args().nth(2))?,
56-
"query-check" => tasks::querycheck()?,
63+
"query-check" => tasks::query_check()?,
64+
"theme-keys-check" => tasks::theme_keys_check()?,
5765
invalid => return Err(format!("Invalid task name: {}", invalid).into()),
5866
},
5967
};

0 commit comments

Comments
 (0)