Skip to content

Commit

Permalink
chore(build): auto-generate docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@github-actions
github-actions[bot] committed Aug 16, 2024
1 parent 247699a commit 213bd2c
Show file tree
Hide file tree
Showing 7 changed files with 269 additions and 101 deletions.
212 changes: 153 additions & 59 deletions docs/config.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,15 @@
---
title: Configuration
title: Config
description: Configuration for care.nvim
sidebar_position: 2
---

# Config

<details>
<summary>Full Default Config</summary>

```lua
---@type care.config
{
config.defaults = {
ui = {
menu = {
max_height = 10,
Expand Down Expand Up @@ -80,6 +78,7 @@ sidebar_position: 2
vim.snippet.expand(snippet_body)
end,
selection_behavior = "select",
confirm_behavior = "insert",
keyword_pattern = [[\%(-\?\d\+\%(\.\d\+\)\?\|\h\w*\%(-\w*\)*\)]],
sources = {},
preselect = true,
Expand All @@ -96,48 +95,125 @@ sidebar_position: 2

</details>

The config of care is used to configure the ui and care itself.
# `care.config`

# Methods

## Snippet Expansion
`config.snippet_expansion(string): nil`

Here a function for expanding snippets is defined. By default this is the
builtin `vim.snippet.expand()`. You can also use a plugin like luasnip for this
like this:

There are two main parts to the config. The first one is the `ui` field and the
second on is the rest of the configuration which is for configuring the general
behavior of care.
```lua
snippet_expansion = function(body)
require("luasnip").lsp_expand(body)
end
```

## UI
## Enabled
`config.enabled(): boolean`

The ui configuration is used to configure the whole ui of care. One of the main
This function can be used to disable care in certain contexts. By default this
disables care in prompts.
# Fields

## Ui
`config.ui care.config.ui`

The [ui configuration](#Ui-Configuration) is used to configure the whole ui of care. One of the main
goals of this is to be as extensible as possible. This is especially important
for the completion entries. Read more about that under
[Configuration of item display](/design/#configuration-of-item-display).

The most important part for many users will be the `menu` field. It's used to
configure the completion menu.

You can also configure the documentation view just like the main menu.

Lastly the users can also configure the icons which will be used for the
different items.

## Ghost text
## Selection Behavior
`config.selection_behavior "select"|"insert"`

With the selection behavior the user can determine what happens when selecting
an entry. This can either be `"select"` or `"insert"`. Selecting will just
select the entry and do nothing else. Insert will actually insert the text of
the entry (this is not necessarily the whole text).

## Confirm Behavior
`config.confirm_behavior "insert"|"replace"`

Behavior when confirming entry

## Sources
`config.sources care.config.source[]`

Configuration for the different sources

## Completion Events
`config.completion_events string[]`

The `completion_events` table is used to set events for completion. By default
it just contains `"TextChangedI"`. You can set it to an empty table (`{}`) to
disable autocompletion.

## Keyword Pattern
`config.keyword_pattern string`

Pattern used to determine keywords, used to determine what to use for filtering
and what to remove if insert text is used.

## Preselect
`config.preselect boolean`

Whether items should be preselected or not
# `care.config.ui`

# Fields

## Menu
`config.ui.menu care.config.ui.menu`

Configuration of the completion menu of care.nvim

## Docs View
`config.ui.docs_view care.config.ui.docs`

This configuration allows you to configure the documentation view. It consists
of some basic window properties like the border and the maximum height of the
window. It also has a field to define the character used for the scrollbar.

## Type Icons
`config.ui.type_icons care.config.ui.type_icons`

This is a table which defines the different icons.

## Ghost Text
`config.ui.ghost_text care.config.ui.ghost_text`

### Enabled
Configuration of ghost text
# `care.config.ui.ghost_text`

# Fields

## Enabled
`config.ui.ghost_text.enabled boolean`

You can use the `enabled` field to determine whether the ghost text should be
enabled or not. The `position` can either be `"inline"` or `"overlay"`. Inline
will add the text inline right where the cursor is. With the overlay position
the text will overlap with existing text after the cursor.

## Menu
## Position
`config.ui.ghost_text.position "inline"|"overlay"`

This configuration should allow you to completely adapt the completion menu to
your likings.

It includes some basic window properties like the border and the maximum height
of the window. It also has a field to define the character used for the
scrollbar. Set `scrollbar` to `nil` value to disable the scrollbar.
# `care.config.ui.menu`

## Position
# Methods

If the menu should be displayed on top, bottom or automatically
## Format Entry
`config.ui.menu.format_entry(entry: care.entry): { [1]: string, [2]: string }[][]`

Another field is `format_entry`. This is a function which recieves an entry of
the completion menu and determines how it's formatted. For that a table with
Expand All @@ -149,7 +225,6 @@ alignment of each section.
For example you want to have the label of an entry in a red highlight and an
icon in a entry-kind specific color left aligned first and then the source of
the entry right aligned in blue. You could do that like this:

```lua
format_entry = function(entry)
return {
Expand All @@ -161,63 +236,82 @@ format_entry = function(entry)
end,
alignment = { "left", "right" }
```

Notice that there are multiple differences between having one table containing
the chunks for the label and kind and having them separately. The latter would
require another entry in the `alignment` table. It would also change the style
of the menu because the left sides of the icons would be aligned at the same
column and not be next to the labels. In the example there also was some spacing
added in between the two.
# Fields

## Documentation view
## Max Height
`config.ui.menu.max_height integer`

This configuration allows you to configure the documentation view. It consists
of some basic window properties like the border and the maximum height of the
window. It also has a field to define the character used for the scrollbar.
Maximum height of the menu

## Type Icons
## Border
`config.ui.menu.border string|string[]|string[][]`

This is a table which defines the different icons.
The border of the completion menu

## Snippet expansion
## Scrollbar
`config.ui.menu.scrollbar string?`

Here a function for expanding snippets is defined. By default this is the
builtin `vim.snippet.expand()`. You can also use a plugin like luasnip for this
like this:
Character used for the scrollbar

```lua
snippet_expansion = function(body)
require("luasnip").lsp_expand(body)
end
```
## Position
`config.ui.menu.position "auto"|"bottom"|"top"`

## Selection behavior
If the menu should be displayed on top, bottom or automatically

With the selection behavior the user can determine what happens when selecting
an entry. This can either be `"select"` or `"insert"`. Selecting will just
select the entry and do nothing else. Insert will actually insert the text of
the entry (this is not necessarily the whole text).
## Alignment
`config.ui.menu.alignment ("left"|"center"|"right")[]`

## Keyword pattern
How the sections in the menu should be aligned
# `care.config.source`

Pattern used to determine keywords, used to determine what to use for filtering
and what to remove if insert text is used.
# Methods

## Completion events
## Enabled
`config.source.enabled boolean|nil|fun():boolean`

The `completion_events` table is used to set events for completion. By default
it just contains `"TextChangedI"`. You can set it to an empty table (`{}`) to
disable autocompletion.
Whether the source is enabled (default true)

## Sources
## Filter
`config.source.filter(entry: care.entry): boolean`

TODO
Filter function for entries by the source
# Fields

## Preselect
## Max Entries
`config.source.max_entries integer?`

Whether items should be preselected or not
The maximum amount of entries which can be displayed by this source

## Enabled
## Priority
`config.source.priority integer?`

This function can be used to disable care in certain contexts. By default this
disables care in prompts.
The priority of this source. Is more important than matching score
# `care.config.ui.docs`

# Fields

## Max Height
`config.ui.docs.max_height integer`

Maximum height of the documentation view

## Max Width
`config.ui.docs.max_width integer`

Maximum width of the documentation view

## Border
`config.ui.docs.border string|string[]|string[][]`

The border of the documentation view

## Scrollbar
`config.ui.docs.scrollbar string`

Character used for the scrollbar
22 changes: 16 additions & 6 deletions docs/dev/context.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,23 +11,31 @@ description: Type description of care.context, care.context.cursor
## Changed
`context.changed(care.context): boolean`

Whether the context changed in comparison to the previous one. This is used to check whether to get new completions or not when using autocompletion.
Whether the context changed in comparison to the previous one. This is used to
check whether to get new completions or not when using autocompletion.

## New
`Context.new(previous: care.context?): care.context`

Create a new context. This takes a previous context as argument. This one is stored to determine if the context changed or not when completing. The previous context of the previous one is deleted so this data structure doesn't grow really large.
Create a new context. This takes a previous context as argument. This one is
stored to determine if the context changed or not when completing. The previous
context of the previous one is deleted so this data structure doesn't grow
really large.
# Fields

## Previous
`context.previous care.context?`

The previous context which is used to determine whether the context changed or not. The `previous` field of the previous context should always be `nil` so the data structure doesn't grow infinitely.
The previous context which is used to determine whether the context changed or
not. The `previous` field of the previous context should always be `nil` so the
data structure doesn't grow infinitely.

## Cursor
`context.cursor care.context.cursor`

The cursor position. This will have a `col` and a `row` field and has 1-based line and 0-based column indexes. This is the same as in `nvim_win_{get, set}_cursor()` (`:h api-indexing`).
The cursor position. This will have a `col` and a `row` field and has 1-based
line and 0-based column indexes. This is the same as in
`nvim_win_{get, set}_cursor()` (`:h api-indexing`).

## Bufnr
`context.bufnr integer`
Expand All @@ -37,7 +45,8 @@ Number of the buffer.
## Reason
`context.reason care.completionReason?`

Reason for triggering completion. This is a `completionReason` so either 1 for automatic triggering and 2 for manual triggering.
Reason for triggering completion. This is a `completionReason` so either 1 for
automatic triggering and 2 for manual triggering.

## Line
`context.line string`
Expand All @@ -47,7 +56,8 @@ The complete line on which the cursor was when the context was created.
## Line Before Cursor
`context.line_before_cursor string`

The line before the cursor. This is mostly important to be correct in insert mode. In normal mode the character on which the cursor is is not included.
The line before the cursor. This is mostly important to be correct in insert
mode. In normal mode the character on which the cursor is is not included.
# `care.context.cursor`

# Fields
Expand Down
Loading

0 comments on commit 213bd2c

Please sign in to comment.