Skip to content

Commit

Permalink
highlights: document them all and add a CI check to ensure language h…
Browse files Browse the repository at this point in the history 
…iglights don't add undocumented ones
  • Loading branch information
@poliorcetics
poliorcetics committed Dec 26, 2022
1 parent 014c08e commit 84a658f
Show file tree
Hide file tree
Showing 6 changed files with 641 additions and 162 deletions.
4 changes: 3 additions & 1 deletion .github/workflows/build.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,10 +108,12 @@ jobs:
- name: Generate docs
run: cargo xtask docgen

- name: All highlight queries keys are statically known
run: cargo xtask theme-keys-check

- name: Check uncommitted documentation changes
run: |
git diff
git diff-files --quiet \
|| (echo "Run 'cargo xtask docgen', commit the changes and push again" \
&& exit 1)
193 changes: 193 additions & 0 deletions book/src/generated/theme-table.md
View file

Large diffs are not rendered by default.

158 changes: 2 additions & 156 deletions book/src/themes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,166 +136,12 @@ We use a similar set of scopes as
[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also
[TextMate](https://macromates.com/manual/en/language_grammars) scopes.

- `attribute` - Class attributes, html tag attributes

- `type` - Types
- `builtin` - Primitive types provided by the language (`int`, `usize`)
- `constructor`

- `constant` (TODO: constant.other.placeholder for %v)
- `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)
- `boolean`
- `character`
- `escape`
- `numeric` (numbers)
- `integer`
- `float`

- `string` (TODO: string.quoted.{single, double}, string.raw/.unquoted)?
- `regexp` - Regular expressions
- `special`
- `path`
- `url`
- `symbol` - Erlang/Elixir atoms, Ruby symbols, Clojure keywords

- `comment` - Code comments
- `line` - Single line comments (`//`)
- `block` - Block comments (e.g. (`/* */`)
- `documentation` - Documentation comments (e.g. `///` in Rust)

- `variable` - Variables
- `builtin` - Reserved language variables (`self`, `this`, `super`, etc)
- `parameter` - Function parameters
- `other`
- `member` - Fields of composite data types (e.g. structs, unions)

- `label`

- `punctuation`
- `delimiter` - Commas, colons
- `bracket` - Parentheses, angle brackets, etc.
- `special` - String interpolation brackets.

- `keyword`
- `control`
- `conditional` - `if`, `else`
- `repeat` - `for`, `while`, `loop`
- `import` - `import`, `export`
- `return`
- `exception`
- `operator` - `or`, `in`
- `directive` - Preprocessor directives (`#if` in C)
- `function` - `fn`, `func`
- `storage` - Keywords describing how things are stored
- `type` - The type of something, `class`, `function`, `var`, `let`, etc.
- `modifier` - Storage modifiers like `static`, `mut`, `const`, `ref`, etc.

- `operator` - `||`, `+=`, `>`

- `function`
- `builtin`
- `method`
- `macro`
- `special` (preprocessor in C)

- `tag` - Tags (e.g. `<body>` in HTML)

- `namespace`

- `markup`
- `heading`
- `marker`
- `1`, `2`, `3`, `4`, `5`, `6` - heading text for h1 through h6
- `list`
- `unnumbered`
- `numbered`
- `bold`
- `italic`
- `link`
- `url` - urls pointed to by links
- `label` - non-url link references
- `text` - url and image descriptions in links
- `quote`
- `raw`
- `inline`
- `block`

- `diff` - version control changes
- `plus` - additions
- `minus` - deletions
- `delta` - modifications
- `moved` - renamed or moved files/changes

#### Interface

These scopes are used for theming the editor interface.

- `markup`
- `normal`
- `completion` - for completion doc popup ui
- `hover` - for hover popup ui
- `heading`
- `completion` - for completion doc popup ui
- `hover` - for hover popup ui
- `raw`
- `inline`
- `completion` - for completion doc popup ui
- `hover` - for hover popup ui


| Key | Notes |
| --- | --- |
| `ui.background` | |
| `ui.background.separator` | Picker separator below input line |
| `ui.cursor` | |
| `ui.cursor.insert` | |
| `ui.cursor.select` | |
| `ui.cursor.match` | Matching bracket etc. |
| `ui.cursor.primary` | Cursor with primary selection |
| `ui.gutter` | Gutter |
| `ui.gutter.selected` | Gutter for the line the cursor is on |
| `ui.linenr` | Line numbers |
| `ui.linenr.selected` | Line number for the line the cursor is on |
| `ui.statusline` | Statusline |
| `ui.statusline.inactive` | Statusline (unfocused document) |
| `ui.statusline.normal` | Statusline mode during normal mode ([only if `editor.color-modes` is enabled][editor-section]) |
| `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |
| `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |
| `ui.statusline.separator` | Separator character in statusline |
| `ui.popup` | Documentation popups (e.g Space + k) |
| `ui.popup.info` | Prompt for multiple key options |
| `ui.window` | Border lines separating splits |
| `ui.help` | Description box for commands |
| `ui.text` | Command prompts, popup text, etc. |
| `ui.text.focus` | |
| `ui.text.inactive` | Same as `ui.text` but when the text is inactive (e.g. suggestions) |
| `ui.text.info` | The key: command text in `ui.popup.info` boxes |
| `ui.virtual.ruler` | Ruler columns (see the [`editor.rulers` config][editor-section]) |
| `ui.virtual.whitespace` | Visible whitespace characters |
| `ui.virtual.indent-guide` | Vertical indent width guides |
| `ui.menu` | Code and command completion menus |
| `ui.menu.selected` | Selected autocomplete item |
| `ui.menu.scroll` | `fg` sets thumb color, `bg` sets track color of scrollbar |
| `ui.selection` | For selections in the editing area |
| `ui.selection.primary` | |
| `ui.cursorline.primary` | The line of the primary cursor ([if cursorline is enabled][editor-section]) |
| `ui.cursorline.secondary` | The lines of any other cursors ([if cursorline is enabled][editor-section]) |
| `ui.cursorcolumn.primary` | The column of the primary cursor ([if cursorcolumn is enabled][editor-section]) |
| `ui.cursorcolumn.secondary` | The columns of any other cursors ([if cursorcolumn is enabled][editor-section]) |
| `warning` | Diagnostics warning (gutter) |
| `error` | Diagnostics error (gutter) |
| `info` | Diagnostics info (gutter) |
| `hint` | Diagnostics hint (gutter) |
| `diagnostic` | Diagnostics fallback style (editing area) |
| `diagnostic.hint` | Diagnostics hint (editing area) |
| `diagnostic.info` | Diagnostics info (editing area) |
| `diagnostic.warning` | Diagnostics warning (editing area) |
| `diagnostic.error` | Diagnostics error (editing area) |
**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.

You can check compliance to spec with

```shell
cargo xtask themelint onedark # replace onedark with <name>
```

[editor-section]: ./configuration.md#editor-section
{{#include generated/theme-table.md}}
1 change: 1 addition & 0 deletions xtask/src/docgen.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ use std::fs;

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

fn md_table_heading(cols: &[String]) -> String {
let mut header = String::new();
Expand Down
18 changes: 13 additions & 5 deletions xtask/src/main.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,29 @@ mod docgen;
mod helpers;
mod path;
mod querycheck;
mod themekeyscheck;
mod themelint;

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

type DynError = Box<dyn Error>;

pub mod tasks {
use crate::docgen::{lang_features, typable_commands, write};
use crate::docgen::{LANG_SUPPORT_MD_OUTPUT, TYPABLE_COMMANDS_MD_OUTPUT};
use crate::querycheck::query_check;
use crate::docgen::{
lang_features, typable_commands, write, LANG_SUPPORT_MD_OUTPUT, THEME_TABLE_MD_OUTPUT,
TYPABLE_COMMANDS_MD_OUTPUT,
};
use crate::themekeyscheck::theme_keys_doc;
use crate::themelint::{lint, lint_all};
use crate::DynError;
// Reexports for direct usage
pub use crate::querycheck::query_check;
pub use crate::themekeyscheck::theme_keys_check;

pub fn docgen() -> Result<(), DynError> {
write(TYPABLE_COMMANDS_MD_OUTPUT, &typable_commands()?);
write(LANG_SUPPORT_MD_OUTPUT, &lang_features()?);
write(THEME_TABLE_MD_OUTPUT, &theme_keys_doc());
Ok(())
}

Expand All @@ -36,11 +43,11 @@ pub mod tasks {
println!(
"
Usage: Run with `cargo xtask <task>`, eg. `cargo xtask docgen`.
Tasks:
docgen: Generate files to be included in the mdbook output.
themelint <theme>: Report errors for <theme>, or all themes if no theme is specified.
query-check: Check that tree-sitter queries are valid.
theme-keys-check: Check that all highlight queries are documented.
"
);
}
Expand All @@ -53,7 +60,8 @@ fn main() -> Result<(), DynError> {
Some(t) => match t.as_str() {
"docgen" => tasks::docgen()?,
"themelint" => tasks::themelint(env::args().nth(2))?,
"query-check" => tasks::querycheck()?,
"query-check" => tasks::query_check()?,
"theme-keys-check" => tasks::theme_keys_check()?,
invalid => return Err(format!("Invalid task name: {}", invalid).into()),
},
};
Expand Down
Loading

0 comments on commit 84a658f

Please sign in to comment.