mirror of
https://github.com/NotAShelf/nvf.git
synced 2024-11-30 00:26:45 +00:00
docs: format via deno fmt
This should be a pre-commit hook in the future.
This commit is contained in:
parent
e43a067cae
commit
a196e9610f
GPG key ID:
AF26552424E53993
11 changed files with 114 additions and 117 deletions
|
|
@ -1,8 +1,8 @@
|
|||
# Custom Plugins {#ch-custom-plugins}
|
||||
|
||||
**nvf**, by default, exposes a wide variety of plugins as module options
|
||||
for your convenience and bundles necessary dependencies into **nvf**'s runtime.
|
||||
In case a plugin is not available in **nvf**, you may consider making a pull
|
||||
**nvf**, by default, exposes a wide variety of plugins as module options for
|
||||
your convenience and bundles necessary dependencies into **nvf**'s runtime. In
|
||||
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
|
||||
configuration locally.
|
||||
|
||||
|
|
@ -11,12 +11,12 @@ configuration locally.
|
|||
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
|
||||
plugin to the runtime, you need to add it to the `vim.startPlugins` list in
|
||||
your configuration.
|
||||
plugin to the runtime, you need to add it to the `vim.startPlugins` list in your
|
||||
configuration.
|
||||
|
||||
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
|
||||
custom plugins that you might have added to your configuration.
|
||||
that you have adeed, but **nvf** provides multiple way of configuring any custom
|
||||
plugins that you might have added to your configuration.
|
||||
|
||||
```{=include=} sections
|
||||
custom-plugins/configuring.md
|
||||
|
|
|
|||
|
|
@ -12,9 +12,9 @@ entries in nvf:
|
|||
2. `globalsScript` - used to set globals defined in `vim.globals`
|
||||
3. `basic` - used to set basic configuration options
|
||||
4. `optionsScript` - used to set options defined in `vim.o`
|
||||
5. `theme` (this is simply placed before `pluginConfigs` and `lazyConfigs`, meaning that
|
||||
surrounding entries don't depend on it) - used to set up the theme, which has to be done before
|
||||
other plugins
|
||||
5. `theme` (this is simply placed before `pluginConfigs` and `lazyConfigs`,
|
||||
meaning that surrounding entries don't depend on it) - used to set up the
|
||||
theme, which has to be done before other plugins
|
||||
6. `lazyConfigs` - `lz.n` and `lzn-auto-require` configs. If `vim.lazy.enable`
|
||||
is false, this will contain each plugin's config instead.
|
||||
7. `pluginConfigs` - the result of the nested `vim.pluginRC` (internal option,
|
||||
|
|
|
|||
|
|
@ -1,25 +1,23 @@
|
|||
# Using DAGs {#ch-using-dags}
|
||||
|
||||
We conform to the NixOS options types for the most part, however, a noteworthy
|
||||
addition for certain options is the [**DAG
|
||||
(Directed acyclic graph)**](https://en.wikipedia.org/wiki/Directed_acyclic_graph)
|
||||
addition for certain options is the
|
||||
[**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
|
||||
used for topologically sorting strings. The DAG type allows the attribute set
|
||||
entries to express dependency relations among themselves. This can, for
|
||||
example, be used to control the order of configuration sections in your
|
||||
`luaConfigRC`.
|
||||
entries to express dependency relations among themselves. This can, for example,
|
||||
be used to control the order of configuration sections in your `luaConfigRC`.
|
||||
|
||||
The below section, mostly taken from the [home-manager
|
||||
manual](https://raw.githubusercontent.com/nix-community/home-manager/master/docs/manual/writing-modules/types.md)
|
||||
The below section, mostly taken from the
|
||||
[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.
|
||||
|
||||
## entryAnywhere {#sec-types-dag-entryAnywhere}
|
||||
|
||||
> `lib.dag.entryAnywhere (value: T) : DagEntry<T>`
|
||||
|
||||
Indicates that `value` can be placed anywhere within the DAG.
|
||||
This is also the default for plain attribute set entries, that
|
||||
is
|
||||
Indicates that `value` can be placed anywhere within the DAG. This is also the
|
||||
default for plain attribute set entries, that is
|
||||
|
||||
```nix
|
||||
foo.bar = {
|
||||
|
|
@ -41,8 +39,8 @@ are equivalent.
|
|||
|
||||
> `lib.dag.entryAfter (afters: list string) (value: T) : DagEntry<T>`
|
||||
|
||||
Indicates that `value` must be placed _after_ each of the
|
||||
attribute names in the given list. For example
|
||||
Indicates that `value` must be placed _after_ each of the attribute names in the
|
||||
given list. For example
|
||||
|
||||
```nix
|
||||
foo.bar = {
|
||||
|
|
@ -57,8 +55,8 @@ would place `b` after `a` in the graph.
|
|||
|
||||
> `lib.dag.entryBefore (befores: list string) (value: T) : DagEntry<T>`
|
||||
|
||||
Indicates that `value` must be placed _before_ each of the
|
||||
attribute names in the given list. For example
|
||||
Indicates that `value` must be placed _before_ each of the attribute names in
|
||||
the given list. For example
|
||||
|
||||
```nix
|
||||
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>`
|
||||
|
||||
Indicates that `value` must be placed _before_ the attribute
|
||||
names in the first list and _after_ the attribute names in the
|
||||
second list. For example
|
||||
Indicates that `value` must be placed _before_ the attribute names in the first
|
||||
list and _after_ the attribute names in the second list. For example
|
||||
|
||||
```nix
|
||||
foo.bar = {
|
||||
|
|
@ -87,18 +84,18 @@ foo.bar = {
|
|||
|
||||
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.
|
||||
These are convenient when you just want to have a linear list of DAG
|
||||
entries, without having to manually enter the relationship between
|
||||
each entry. Each of these functions take a `tag` as argument and the
|
||||
DAG entries will be named `${tag}-${index}`.
|
||||
There are also a set of functions that generate a DAG from a list. These are
|
||||
convenient when you just want to have a linear list of DAG entries, without
|
||||
having to manually enter the relationship between each entry. Each of these
|
||||
functions take a `tag` as argument and the DAG entries will be named
|
||||
`${tag}-${index}`.
|
||||
|
||||
## entriesAnywhere {#sec-types-dag-entriesAnywhere}
|
||||
|
||||
> `lib.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T>`
|
||||
|
||||
Creates a DAG with the given values with each entry labeled
|
||||
using the given tag. For example
|
||||
Creates a DAG with the given values with each entry labeled using the given tag.
|
||||
For example
|
||||
|
||||
```nix
|
||||
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>`
|
||||
|
||||
Creates a DAG with the given values with each entry labeled
|
||||
using the given tag. The list of values are placed are placed
|
||||
_after_ each of the attribute names in `afters`. For example
|
||||
Creates a DAG with the given values with each entry labeled using the given tag.
|
||||
The list of values are placed are placed _after_ each of the attribute names in
|
||||
`afters`. For example
|
||||
|
||||
```nix
|
||||
foo.bar =
|
||||
|
|
@ -140,12 +137,12 @@ foo.bar = {
|
|||
|
||||
> `lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T>`
|
||||
|
||||
Creates a DAG with the given values with each entry labeled
|
||||
using the given tag. The list of values are placed _before_ each
|
||||
of the attribute names in `befores`. For example
|
||||
Creates a DAG with the given values with each entry labeled using the given tag.
|
||||
The list of values are placed _before_ each of the attribute names in `befores`.
|
||||
For example
|
||||
|
||||
```nix
|
||||
foo.bar =
|
||||
foo.bar =
|
||||
{ b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ];
|
||||
```
|
||||
|
||||
|
|
@ -163,10 +160,9 @@ foo.bar = {
|
|||
|
||||
> `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
|
||||
using the given tag. The list of values are placed _before_ each
|
||||
of the attribute names in `befores` and _after_ each of the
|
||||
attribute names in `afters`. For example
|
||||
Creates a DAG with the given values with each entry labeled using the given tag.
|
||||
The list of values are placed _before_ each of the attribute names in `befores`
|
||||
and _after_ each of the attribute names in `afters`. For example
|
||||
|
||||
```nix
|
||||
foo.bar =
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
Language specific support means there is a combination of language specific
|
||||
plugins, `treesitter` support, `nvim-lspconfig` language servers, and `null-ls`
|
||||
integration. This gets you capabilities ranging from autocompletion to formatting
|
||||
to diagnostics. The following languages have sections under the `vim.languages`
|
||||
attribute.
|
||||
integration. This gets you capabilities ranging from autocompletion to
|
||||
formatting to diagnostics. The following languages have sections under the
|
||||
`vim.languages` attribute.
|
||||
|
||||
- Rust: [vim.languages.rust.enable](#opt-vim.languages.rust.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)
|
||||
- PHP: [vim.languages.php.enable](#opt-vim.languages.php.enable)
|
||||
|
||||
Adding support for more languages, and improving support for existing ones are great places
|
||||
where you can contribute with a PR.
|
||||
Adding support for more languages, and improving support for existing ones are
|
||||
great places where you can contribute with a PR.
|
||||
|
||||
```{=include=} sections
|
||||
languages/lsp.md
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# LSP Custom Packages/Command {#sec-languages-custom-lsp-packages}
|
||||
|
||||
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
|
||||
a list of strings. You can use this to skip automatic installation of a language
|
||||
your own LSP package, or provide the command to launch the language server, as a
|
||||
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
|
||||
example:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
# 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.
|
||||
Here are a few default configurations you can use.
|
||||
While you can configure **nvf** yourself using the builder, you can also use the
|
||||
pre-built configs that are available. Here are a few default configurations you
|
||||
can use.
|
||||
|
||||
```{=include=} chapters
|
||||
default-configs/maximal.md
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
configuration, but with every supported language enabled.
|
||||
|
||||
::: {.note}
|
||||
Running the maximal config will download _a lot_ of packages as it is
|
||||
downloading language servers, formatters, and more.
|
||||
:::
|
||||
::: {.note} Running the maximal config will download _a lot_ of packages as it
|
||||
is downloading language servers, formatters, and more. :::
|
||||
|
|
|
|||
|
|
@ -1,16 +1,17 @@
|
|||
# Getting Started {#sec-contrib-getting-started}
|
||||
|
||||
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/)
|
||||
for instructions on how you can do this. Once you have a fork of **nvf**, you
|
||||
should create a separate branch based on the msot recent `main` branch. Give
|
||||
your branch a reasonably descriptive name (e.g. `feature/debugger` or
|
||||
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/) for
|
||||
instructions on how you can do this. Once you have a fork of **nvf**, you should
|
||||
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
|
||||
|
||||
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
|
||||
Guidelines](#sec-guidelines), push the branch to GitHub and [create a pull
|
||||
request](https://help.github.com/articles/creating-a-pull-request). The default
|
||||
pull request template available on the **nvf** repository will guide you through
|
||||
the rest of the process, and we'll gently nudge you in the correct direction if
|
||||
there are any mistakes.
|
||||
are happy with the result, and positive that it fullfills our
|
||||
[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and
|
||||
[create a pull request](https://help.github.com/articles/creating-a-pull-request).
|
||||
The default pull request template available on the **nvf** repository will guide
|
||||
you through the rest of the process, and we'll gently nudge you in the correct
|
||||
direction if there are any mistakes.
|
||||
|
|
|
|||
|
|
@ -3,30 +3,29 @@
|
|||
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
|
||||
strictly enforced, others will remain as gentle nudges towards the correct
|
||||
direction. As we have no automated system enforcing those guidelines, please
|
||||
try to double check your changes before making your pull request in order to
|
||||
avoid "faulty" code slipping by.
|
||||
direction. As we have no automated system enforcing those guidelines, please try
|
||||
to double check your changes before making your pull request in order to avoid
|
||||
"faulty" code slipping by.
|
||||
|
||||
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)
|
||||
ideally (but not necessarily) before you start developing.
|
||||
then feel free to start a discussion in the
|
||||
[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not
|
||||
necessarily) before you start developing.
|
||||
|
||||
## Adding Documentation {#sec-guidelines-documentation}
|
||||
|
||||
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.
|
||||
|
||||
::: {.note}
|
||||
As of **v0.5**, **nvf** is itself documented using full markdown in both module
|
||||
options and the manual. With **v0.6**, this manual has also been converted to
|
||||
markdown in full.
|
||||
:::
|
||||
::: {.note} As of **v0.5**, **nvf** is itself documented using full markdown in
|
||||
both module options and the manual. With **v0.6**, this manual has also been
|
||||
converted to markdown in full. :::
|
||||
|
||||
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
|
||||
opened by typing the following in a shell within a clone of the **nvf** Git
|
||||
repository:
|
||||
and the documentation of **nvf** (such as this page) can be generated and opened
|
||||
by typing the following in a shell within a clone of the **nvf** Git repository:
|
||||
|
||||
```console
|
||||
$ nix build .#docs-html
|
||||
|
|
@ -35,28 +34,28 @@ $ xdg-open $PWD/result/share/doc/nvf/index.html
|
|||
|
||||
## Formatting Code {#sec-guidelines-formatting}
|
||||
|
||||
Make sure your code is formatted as described in [code-style
|
||||
section](#sec-guidelines-code-style). To maintain consistency throughout the
|
||||
project you are encouraged to browse through existing code and adopt its style
|
||||
also in new code.
|
||||
Make sure your code is formatted as described in
|
||||
[code-style section](#sec-guidelines-code-style). To maintain consistency
|
||||
throughout the project you are encouraged to browse through existing code and
|
||||
adopt its style also in new code.
|
||||
|
||||
## Formatting Commits {#sec-guidelines-commit-message-style}
|
||||
|
||||
Similar to [code style guidelines](#sec-guidelines-code-style) we encourage a
|
||||
consistent commit message format as described in [commit style
|
||||
guidelines](#sec-guidelines-commit-style).
|
||||
consistent commit message format as described in
|
||||
[commit style guidelines](#sec-guidelines-commit-style).
|
||||
|
||||
## Commit Style {#sec-guidelines-commit-style}
|
||||
|
||||
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
|
||||
own and in general context. That is, a second commit should not resolve an
|
||||
issue that is introduced in an earlier commit. In particular, you will be
|
||||
asked to amend any commit that introduces syntax errors or similar problems
|
||||
even if they are fixed in a later commit.
|
||||
means each and every commit in a pull request should make sense both on its own
|
||||
and in general context. That is, a second commit should not resolve an issue
|
||||
that is introduced in an earlier commit. In particular, you will be asked to
|
||||
amend any commit that introduces syntax errors or similar problems even if they
|
||||
are fixed in a later commit.
|
||||
|
||||
The commit messages should follow the [seven
|
||||
rules](https://chris.beams.io/posts/git-commit/#seven-rule), except for
|
||||
The commit messages should follow the
|
||||
[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
|
||||
component or module in the first line. A commit message ideally, but not
|
||||
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
|
||||
affects, `{description}` is a very brief description of your change, and
|
||||
`{long description}` is an optional clarifying description. As a rare
|
||||
exception, if there is no clear component, or your change affects many
|
||||
components, then the `{component}` part is optional. See [example commit
|
||||
message](#sec-guidelines-ex-commit-message) for a commit message that
|
||||
fulfills these requirements.
|
||||
`{long description}` is an optional clarifying description. As a rare exception,
|
||||
if there is no clear component, or your change affects many components, then the
|
||||
`{component}` part is optional. See
|
||||
[example commit message](#sec-guidelines-ex-commit-message) for a commit message
|
||||
that fulfills these requirements.
|
||||
|
||||
## 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.
|
||||
|
||||
```
|
||||
|
|
@ -112,21 +112,22 @@ to contain the parent as well - for example `languages/java: some major change`.
|
|||
|
||||
### Treewide {#sec-code-style-treewide}
|
||||
|
||||
Keep lines at a reasonable width, ideally 80 characters or less. This also applies
|
||||
to string literals and module descriptions and documentation.
|
||||
Keep lines at a reasonable width, ideally 80 characters or less. This also
|
||||
applies to string literals and module descriptions and documentation.
|
||||
|
||||
### Nix {#sec-code-style-nix}
|
||||
|
||||
**nvf** is formatted by the [alejandra](https://github.com/kamadorueda/alejandra)
|
||||
tool and the formatting is checked in the pull request and push workflows. Run the
|
||||
`nix fmt` command inside the project repository before submitting your pull request.
|
||||
**nvf** is formatted by the
|
||||
[alejandra](https://github.com/kamadorueda/alejandra) tool and the formatting is
|
||||
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,
|
||||
certain changes are done at the user's discretion based on how the original
|
||||
code was structured.
|
||||
certain changes are done at the user's discretion based on how the original code
|
||||
was structured.
|
||||
|
||||
Please use one line code for attribute sets that contain only one subset.
|
||||
For example:
|
||||
Please use one line code for attribute sets that contain only one subset. For
|
||||
example:
|
||||
|
||||
```nix
|
||||
# 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,
|
||||
but please try to unfold lists if they contain multiple items and especially
|
||||
if they are to include comments.
|
||||
but please try to unfold lists if they contain multiple items and especially if
|
||||
they are to include comments.
|
||||
|
||||
```nix
|
||||
# this is ok
|
||||
|
|
|
|||
|
|
@ -11,5 +11,5 @@ as posssible.
|
|||
|
||||
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
|
||||
`configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same procedure
|
||||
as adding a new module will apply here.
|
||||
`configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same
|
||||
procedure as adding a new module will apply here.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Release Notes {#ch-release-notes}
|
||||
|
||||
This section lists the release notes for tagged version of **nvf** and
|
||||
the current main current main branch
|
||||
This section lists the release notes for tagged version of **nvf** and the
|
||||
current main current main branch
|
||||
|
||||
```{=include=} chapters
|
||||
rl-0.1.md
|
||||
|
|
|
|||
Loading…
Reference in a new issue