raf/neovim-flake
1
0
Fork 0
mirror of https://github.com/NotAShelf/neovim-flake.git synced 2024-12-19 06:29:47 +01:00
Code Issues Projects Releases Packages Wiki Activity

docs: format via deno fmt

Browse source 
This should be a pre-commit hook in the future.
This commit is contained in:
NotAShelf 2024-11-25 19:16:46 +03:00
parent e43a067cae
commit a196e9610f
No known key found for this signature in database
GPG key ID: AF26552424E53993
11 changed files with 114 additions and 117 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
docs/manual/configuring/custom-plugins.md
View file

@ -1,8 +1,8 @@
# Custom Plugins {#ch-custom-plugins} # Custom Plugins {#ch-custom-plugins}
**nvf**, by default, exposes a wide variety of plugins as module options **nvf**, by default, exposes a wide variety of plugins as module options for
for your convenience and bundles necessary dependencies into **nvf**'s runtime. your convenience and bundles necessary dependencies into **nvf**'s runtime. In
In case a plugin is not available in **nvf**, you may consider making a pull case a plugin is not available in **nvf**, you may consider making a pull
request to **nvf** to include it as a module or you may add it to your request to **nvf** to include it as a module or you may add it to your
configuration locally. configuration locally.
@ -11,12 +11,12 @@ configuration locally.
There are multiple ways of adding custom plugins to your **nvf** configuration. There are multiple ways of adding custom plugins to your **nvf** configuration.
You can use custom plugins, before they are implemented in the flake. To add a You can use custom plugins, before they are implemented in the flake. To add a
plugin to the runtime, you need to add it to the `vim.startPlugins` list in plugin to the runtime, you need to add it to the `vim.startPlugins` list in your
your configuration. configuration.
Adding a plugin to `startPlugins` will not allow you to configure the plugin Adding a plugin to `startPlugins` will not allow you to configure the plugin
that you have adeed, but **nvf** provides multiple way of configuring any that you have adeed, but **nvf** provides multiple way of configuring any custom
custom plugins that you might have added to your configuration. plugins that you might have added to your configuration.
```{=include=} sections ```{=include=} sections
custom-plugins/configuring.md custom-plugins/configuring.md

6
docs/manual/configuring/dag-entries.md
View file

@ -12,9 +12,9 @@ entries in nvf:
2. `globalsScript` - used to set globals defined in `vim.globals` 2. `globalsScript` - used to set globals defined in `vim.globals`
3. `basic` - used to set basic configuration options 3. `basic` - used to set basic configuration options
4. `optionsScript` - used to set options defined in `vim.o` 4. `optionsScript` - used to set options defined in `vim.o`
5. `theme` (this is simply placed before `pluginConfigs` and `lazyConfigs`, meaning that 5. `theme` (this is simply placed before `pluginConfigs` and `lazyConfigs`,
surrounding entries don't depend on it) - used to set up the theme, which has to be done before meaning that surrounding entries don't depend on it) - used to set up the
other plugins theme, which has to be done before other plugins
6. `lazyConfigs` - `lz.n` and `lzn-auto-require` configs. If `vim.lazy.enable` 6. `lazyConfigs` - `lz.n` and `lzn-auto-require` configs. If `vim.lazy.enable`
is false, this will contain each plugin's config instead. is false, this will contain each plugin's config instead.
7. `pluginConfigs` - the result of the nested `vim.pluginRC` (internal option, 7. `pluginConfigs` - the result of the nested `vim.pluginRC` (internal option,

68
docs/manual/configuring/dags.md
View file

@ -1,25 +1,23 @@
# Using DAGs {#ch-using-dags} # Using DAGs {#ch-using-dags}
We conform to the NixOS options types for the most part, however, a noteworthy We conform to the NixOS options types for the most part, however, a noteworthy
addition for certain options is the [**DAG addition for certain options is the
(Directed acyclic graph)**](https://en.wikipedia.org/wiki/Directed_acyclic_graph) [**DAG (Directed acyclic graph)**](https://en.wikipedia.org/wiki/Directed_acyclic_graph)
type which is borrowed from home-manager's extended library. This type is most type which is borrowed from home-manager's extended library. This type is most
used for topologically sorting strings. The DAG type allows the attribute set used for topologically sorting strings. The DAG type allows the attribute set
entries to express dependency relations among themselves. This can, for entries to express dependency relations among themselves. This can, for example,
example, be used to control the order of configuration sections in your be used to control the order of configuration sections in your `luaConfigRC`.
`luaConfigRC`.
The below section, mostly taken from the [home-manager The below section, mostly taken from the
manual](https://raw.githubusercontent.com/nix-community/home-manager/master/docs/manual/writing-modules/types.md) [home-manager manual](https://raw.githubusercontent.com/nix-community/home-manager/master/docs/manual/writing-modules/types.md)
explains in more detail the overall usage logic of the DAG type. explains in more detail the overall usage logic of the DAG type.
## entryAnywhere {#sec-types-dag-entryAnywhere} ## entryAnywhere {#sec-types-dag-entryAnywhere}
> `lib.dag.entryAnywhere (value: T) : DagEntry<T>` > `lib.dag.entryAnywhere (value: T) : DagEntry<T>`
Indicates that `value` can be placed anywhere within the DAG. Indicates that `value` can be placed anywhere within the DAG. This is also the
This is also the default for plain attribute set entries, that default for plain attribute set entries, that is
is
```nix ```nix
foo.bar = { foo.bar = {
@ -41,8 +39,8 @@ are equivalent.
> `lib.dag.entryAfter (afters: list string) (value: T) : DagEntry<T>` > `lib.dag.entryAfter (afters: list string) (value: T) : DagEntry<T>`
Indicates that `value` must be placed _after_ each of the Indicates that `value` must be placed _after_ each of the attribute names in the
attribute names in the given list. For example given list. For example
```nix ```nix
foo.bar = { foo.bar = {
@ -57,8 +55,8 @@ would place `b` after `a` in the graph.
> `lib.dag.entryBefore (befores: list string) (value: T) : DagEntry<T>` > `lib.dag.entryBefore (befores: list string) (value: T) : DagEntry<T>`
Indicates that `value` must be placed _before_ each of the Indicates that `value` must be placed _before_ each of the attribute names in
attribute names in the given list. For example the given list. For example
```nix ```nix
foo.bar = { foo.bar = {
@ -73,9 +71,8 @@ would place `b` before `a` in the graph.
> `lib.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry<T>` > `lib.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry<T>`
Indicates that `value` must be placed _before_ the attribute Indicates that `value` must be placed _before_ the attribute names in the first
names in the first list and _after_ the attribute names in the list and _after_ the attribute names in the second list. For example
second list. For example
```nix ```nix
foo.bar = { foo.bar = {
@ -87,18 +84,18 @@ foo.bar = {
would place `c` before `b` and after `a` in the graph. would place `c` before `b` and after `a` in the graph.
There are also a set of functions that generate a DAG from a list. There are also a set of functions that generate a DAG from a list. These are
These are convenient when you just want to have a linear list of DAG convenient when you just want to have a linear list of DAG entries, without
entries, without having to manually enter the relationship between having to manually enter the relationship between each entry. Each of these
each entry. Each of these functions take a `tag` as argument and the functions take a `tag` as argument and the DAG entries will be named
DAG entries will be named `${tag}-${index}`. `${tag}-${index}`.
## entriesAnywhere {#sec-types-dag-entriesAnywhere} ## entriesAnywhere {#sec-types-dag-entriesAnywhere}
> `lib.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T>` > `lib.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T>`
Creates a DAG with the given values with each entry labeled Creates a DAG with the given values with each entry labeled using the given tag.
using the given tag. For example For example
```nix ```nix
foo.bar = lib.dag.entriesAnywhere "a" [ 0 1 ]; foo.bar = lib.dag.entriesAnywhere "a" [ 0 1 ];
@ -117,9 +114,9 @@ foo.bar = {
> `lib.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag<T>` > `lib.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag<T>`
Creates a DAG with the given values with each entry labeled Creates a DAG with the given values with each entry labeled using the given tag.
using the given tag. The list of values are placed are placed The list of values are placed are placed _after_ each of the attribute names in
_after_ each of the attribute names in `afters`. For example `afters`. For example
```nix ```nix
foo.bar = foo.bar =
@ -140,13 +137,13 @@ foo.bar = {
> `lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T>` > `lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T>`
Creates a DAG with the given values with each entry labeled Creates a DAG with the given values with each entry labeled using the given tag.
using the given tag. The list of values are placed _before_ each The list of values are placed _before_ each of the attribute names in `befores`.
of the attribute names in `befores`. For example For example
```nix ```nix
foo.bar = foo.bar =
{ b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ]; { b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ];
``` ```
is equivalent to is equivalent to
@ -163,10 +160,9 @@ foo.bar = {
> `lib.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag<T>` > `lib.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag<T>`
Creates a DAG with the given values with each entry labeled Creates a DAG with the given values with each entry labeled using the given tag.
using the given tag. The list of values are placed _before_ each The list of values are placed _before_ each of the attribute names in `befores`
of the attribute names in `befores` and _after_ each of the and _after_ each of the attribute names in `afters`. For example
attribute names in `afters`. For example
```nix ```nix
foo.bar = foo.bar =

10
docs/manual/configuring/languages.md
View file

@ -2,9 +2,9 @@
Language specific support means there is a combination of language specific Language specific support means there is a combination of language specific
plugins, `treesitter` support, `nvim-lspconfig` language servers, and `null-ls` plugins, `treesitter` support, `nvim-lspconfig` language servers, and `null-ls`
integration. This gets you capabilities ranging from autocompletion to formatting integration. This gets you capabilities ranging from autocompletion to
to diagnostics. The following languages have sections under the `vim.languages` formatting to diagnostics. The following languages have sections under the
attribute. `vim.languages` attribute.
- Rust: [vim.languages.rust.enable](#opt-vim.languages.rust.enable) - Rust: [vim.languages.rust.enable](#opt-vim.languages.rust.enable)
- Nix: [vim.languages.nix.enable](#opt-vim.languages.nix.enable) - Nix: [vim.languages.nix.enable](#opt-vim.languages.nix.enable)
@ -20,8 +20,8 @@ attribute.
- Lua: [vim.languages.lua.enable](#opt-vim.languages.lua.enable) - Lua: [vim.languages.lua.enable](#opt-vim.languages.lua.enable)
- PHP: [vim.languages.php.enable](#opt-vim.languages.php.enable) - PHP: [vim.languages.php.enable](#opt-vim.languages.php.enable)
Adding support for more languages, and improving support for existing ones are great places Adding support for more languages, and improving support for existing ones are
where you can contribute with a PR. great places where you can contribute with a PR.
```{=include=} sections ```{=include=} sections
languages/lsp.md languages/lsp.md

4
docs/manual/configuring/languages/lsp.md
View file

@ -1,8 +1,8 @@
# LSP Custom Packages/Command {#sec-languages-custom-lsp-packages} # LSP Custom Packages/Command {#sec-languages-custom-lsp-packages}
In any of the `opt.languages.<language>.lsp.package` options you can provide In any of the `opt.languages.<language>.lsp.package` options you can provide
your own LSP package, or provide the command to launch the language server, as your own LSP package, or provide the command to launch the language server, as a
a list of strings. You can use this to skip automatic installation of a language list of strings. You can use this to skip automatic installation of a language
server, and instead use the one found in your `$PATH` during runtime, for server, and instead use the one found in your `$PATH` during runtime, for
example: example:

5
docs/manual/default-configs.md
View file

@ -1,7 +1,8 @@
# Default Configs {#ch-default-configs} # Default Configs {#ch-default-configs}
While you can configure **nvf** yourself using the builder, you can also use the pre-built configs that are available. While you can configure **nvf** yourself using the builder, you can also use the
Here are a few default configurations you can use. pre-built configs that are available. Here are a few default configurations you
can use.
```{=include=} chapters ```{=include=} chapters
default-configs/maximal.md default-configs/maximal.md

6
docs/manual/default-configs/maximal.md
View file

@ -7,7 +7,5 @@ $ nix shell github:notashelf/nvf#maximal test.nix
It is the same fully configured Neovim as with the [Nix](#sec-default-nix) It is the same fully configured Neovim as with the [Nix](#sec-default-nix)
configuration, but with every supported language enabled. configuration, but with every supported language enabled.
::: {.note} ::: {.note} Running the maximal config will download _a lot_ of packages as it
Running the maximal config will download _a lot_ of packages as it is is downloading language servers, formatters, and more. :::
downloading language servers, formatters, and more.
:::

21
docs/manual/hacking/getting-started.md
View file

@ -1,16 +1,17 @@
# Getting Started {#sec-contrib-getting-started} # Getting Started {#sec-contrib-getting-started}
You, naturally, would like to start by forking the repository to get started. If You, naturally, would like to start by forking the repository to get started. If
you are new to Git and GitHub, do have a look at GitHub's [Fork a repo guide](https://help.github.com/articles/fork-a-repo/) you are new to Git and GitHub, do have a look at GitHub's
for instructions on how you can do this. Once you have a fork of **nvf**, you [Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for
should create a separate branch based on the msot recent `main` branch. Give instructions on how you can do this. Once you have a fork of **nvf**, you should
your branch a reasonably descriptive name (e.g. `feature/debugger` or create a separate branch based on the msot recent `main` branch. Give your
branch a reasonably descriptive name (e.g. `feature/debugger` or
`fix/pesky-bug`) and you are ready to work on your changes `fix/pesky-bug`) and you are ready to work on your changes
Implement your changes and commit them to the newly created branch and when you Implement your changes and commit them to the newly created branch and when you
are happy with the result, and positive that it fullfills our [Contributing are happy with the result, and positive that it fullfills our
Guidelines](#sec-guidelines), push the branch to GitHub and [create a pull [Contributing Guidelines](#sec-guidelines), push the branch to GitHub and
request](https://help.github.com/articles/creating-a-pull-request). The default [create a pull request](https://help.github.com/articles/creating-a-pull-request).
pull request template available on the **nvf** repository will guide you through The default pull request template available on the **nvf** repository will guide
the rest of the process, and we'll gently nudge you in the correct direction if you through the rest of the process, and we'll gently nudge you in the correct
there are any mistakes. direction if there are any mistakes.

89
docs/manual/hacking/guidelines.md
View file

@ -3,30 +3,29 @@
If your contribution tightly follows the guidelines, then there is a good chance If your contribution tightly follows the guidelines, then there is a good chance
it will be merged without too much trouble. Some of the guidelines will be it will be merged without too much trouble. Some of the guidelines will be
strictly enforced, others will remain as gentle nudges towards the correct strictly enforced, others will remain as gentle nudges towards the correct
direction. As we have no automated system enforcing those guidelines, please direction. As we have no automated system enforcing those guidelines, please try
try to double check your changes before making your pull request in order to to double check your changes before making your pull request in order to avoid
avoid "faulty" code slipping by. "faulty" code slipping by.
If you are uncertain how these rules affect the change you would like to make If you are uncertain how these rules affect the change you would like to make
then feel free to start a discussion in the [discussions tab](https://github.com/NotAShelf/nvf/discussions) then feel free to start a discussion in the
ideally (but not necessarily) before you start developing. [discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not
necessarily) before you start developing.
## Adding Documentation {#sec-guidelines-documentation} ## Adding Documentation {#sec-guidelines-documentation}
Most, if not all, changes warrant changes to the documentation. Module options Most, if not all, changes warrant changes to the documentation. Module options
should be documented with [Nixpkgs-flavoured Markdown](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup), should be documented with
[Nixpkgs-flavoured Markdown](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup),
albeit with exceptions. albeit with exceptions.
::: {.note} ::: {.note} As of **v0.5**, **nvf** is itself documented using full markdown in
As of **v0.5**, **nvf** is itself documented using full markdown in both module both module options and the manual. With **v0.6**, this manual has also been
options and the manual. With **v0.6**, this manual has also been converted to converted to markdown in full. :::
markdown in full.
:::
The HTML version of this manual containing both the module option descriptions The HTML version of this manual containing both the module option descriptions
and the documentation of **nvf** (such as this page) can be generated and and the documentation of **nvf** (such as this page) can be generated and opened
opened by typing the following in a shell within a clone of the **nvf** Git by typing the following in a shell within a clone of the **nvf** Git repository:
repository:
```console ```console
$ nix build .#docs-html $ nix build .#docs-html
@ -35,28 +34,28 @@ $ xdg-open $PWD/result/share/doc/nvf/index.html
## Formatting Code {#sec-guidelines-formatting} ## Formatting Code {#sec-guidelines-formatting}
Make sure your code is formatted as described in [code-style Make sure your code is formatted as described in
section](#sec-guidelines-code-style). To maintain consistency throughout the [code-style section](#sec-guidelines-code-style). To maintain consistency
project you are encouraged to browse through existing code and adopt its style throughout the project you are encouraged to browse through existing code and
also in new code. adopt its style also in new code.
## Formatting Commits {#sec-guidelines-commit-message-style} ## Formatting Commits {#sec-guidelines-commit-message-style}
Similar to [code style guidelines](#sec-guidelines-code-style) we encourage a Similar to [code style guidelines](#sec-guidelines-code-style) we encourage a
consistent commit message format as described in [commit style consistent commit message format as described in
guidelines](#sec-guidelines-commit-style). [commit style guidelines](#sec-guidelines-commit-style).
## Commit Style {#sec-guidelines-commit-style} ## Commit Style {#sec-guidelines-commit-style}
The commits in your pull request should be reasonably self-contained. Which The commits in your pull request should be reasonably self-contained. Which
means each and every commit in a pull request should make sense both on its means each and every commit in a pull request should make sense both on its own
own and in general context. That is, a second commit should not resolve an and in general context. That is, a second commit should not resolve an issue
issue that is introduced in an earlier commit. In particular, you will be that is introduced in an earlier commit. In particular, you will be asked to
asked to amend any commit that introduces syntax errors or similar problems amend any commit that introduces syntax errors or similar problems even if they
even if they are fixed in a later commit. are fixed in a later commit.
The commit messages should follow the [seven The commit messages should follow the
rules](https://chris.beams.io/posts/git-commit/#seven-rule), except for [seven rules](https://chris.beams.io/posts/git-commit/#seven-rule), except for
"Capitalize the subject line". We also ask you to include the affected code "Capitalize the subject line". We also ask you to include the affected code
component or module in the first line. A commit message ideally, but not component or module in the first line. A commit message ideally, but not
necessarily, follow the given template from home-manager's own documentation necessarily, follow the given template from home-manager's own documentation
@ -69,15 +68,16 @@ necessarily, follow the given template from home-manager's own documentation
where `{component}` refers to the code component (or module) your change where `{component}` refers to the code component (or module) your change
affects, `{description}` is a very brief description of your change, and affects, `{description}` is a very brief description of your change, and
`{long description}` is an optional clarifying description. As a rare `{long description}` is an optional clarifying description. As a rare exception,
exception, if there is no clear component, or your change affects many if there is no clear component, or your change affects many components, then the
components, then the `{component}` part is optional. See [example commit `{component}` part is optional. See
message](#sec-guidelines-ex-commit-message) for a commit message that [example commit message](#sec-guidelines-ex-commit-message) for a commit message
fulfills these requirements. that fulfills these requirements.
## Example Commit {#sec-guidelines-ex-commit-message} ## Example Commit {#sec-guidelines-ex-commit-message}
The commit [69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef) The commit
[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
in home-manager contains the following commit message. in home-manager contains the following commit message.
``` ```
@ -112,21 +112,22 @@ to contain the parent as well - for example `languages/java: some major change`.
### Treewide {#sec-code-style-treewide} ### Treewide {#sec-code-style-treewide}
Keep lines at a reasonable width, ideally 80 characters or less. This also applies Keep lines at a reasonable width, ideally 80 characters or less. This also
to string literals and module descriptions and documentation. applies to string literals and module descriptions and documentation.
### Nix {#sec-code-style-nix} ### Nix {#sec-code-style-nix}
**nvf** is formatted by the [alejandra](https://github.com/kamadorueda/alejandra) **nvf** is formatted by the
tool and the formatting is checked in the pull request and push workflows. Run the [alejandra](https://github.com/kamadorueda/alejandra) tool and the formatting is
`nix fmt` command inside the project repository before submitting your pull request. checked in the pull request and push workflows. Run the `nix fmt` command inside
the project repository before submitting your pull request.
While Alejandra is mostly opinionated on how code looks after formatting, While Alejandra is mostly opinionated on how code looks after formatting,
certain changes are done at the user's discretion based on how the original certain changes are done at the user's discretion based on how the original code
code was structured. was structured.
Please use one line code for attribute sets that contain only one subset. Please use one line code for attribute sets that contain only one subset. For
For example: example:
```nix ```nix
# parent modules should always be unfolded # parent modules should always be unfolded
@ -158,8 +159,8 @@ module = {
``` ```
For lists, it is mostly up to your own discretion how you want to format them, For lists, it is mostly up to your own discretion how you want to format them,
but please try to unfold lists if they contain multiple items and especially but please try to unfold lists if they contain multiple items and especially if
if they are to include comments. they are to include comments.
```nix ```nix
# this is ok # this is ok

4
docs/manual/hacking/testing.md
View file

@ -11,5 +11,5 @@ as posssible.
If it is not a new module, but a change to an existing one, then make sure the If it is not a new module, but a change to an existing one, then make sure the
module you have changed is enabled in the maximal configuration by editing module you have changed is enabled in the maximal configuration by editing
`configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same procedure `configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same
as adding a new module will apply here. procedure as adding a new module will apply here.

4
docs/release-notes/release-notes.md
View file

@ -1,7 +1,7 @@
# Release Notes {#ch-release-notes} # Release Notes {#ch-release-notes}
This section lists the release notes for tagged version of **nvf** and This section lists the release notes for tagged version of **nvf** and the
the current main current main branch current main current main branch
```{=include=} chapters ```{=include=} chapters
rl-0.1.md rl-0.1.md