mirror of
https://github.com/NotAShelf/nvf.git
synced 2026-01-01 16:45:55 +00:00
docs/manual: fix minor typos; revamp contributing section
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: Ibb76402cc1e759b404a5c8905109604c6a6a6964
This commit is contained in:
parent
1b73e78788
commit
858717bed7
GPG key ID:
29D95B64378DB4BF
2 changed files with 286 additions and 111 deletions
|
|
@ -3,12 +3,13 @@
|
|||
[open issues]: https://github.com/notashelf/nvf/issues
|
||||
[new issue]: https://github.com/notashelf/nvf/issues/new
|
||||
|
||||
nvf is designed for the developer as much as it is designed for the end-user. We
|
||||
would like for any contributor to be able to propagate their changes, or add new
|
||||
features to the project with minimum possible friction. As such, below are the
|
||||
guides and guidelines written to streamline the contribution process and to
|
||||
ensure that your valuable input integrates into nvf's development as seamlessly
|
||||
as possible without leaving any question marks in your head.
|
||||
**nvf** is designed for the developer as much as it is designed for the
|
||||
end-user. We would like for any contributor to be able to propagate their
|
||||
changes, or add new features to the project with minimum possible friction. As
|
||||
such, below are the guides and guidelines written to streamline the contribution
|
||||
process and to ensure that your valuable input integrates into **nvf**'s
|
||||
development as seamlessly as possible without leaving any question marks in your
|
||||
head.
|
||||
|
||||
This section is directed mainly towards those who wish to contribute code into
|
||||
the project. If you instead wish to report a bug, or discuss a potential new
|
||||
|
|
@ -23,24 +24,51 @@ please do not be afraid to submit a pull request, we will help you get it in.
|
|||
|
||||
## 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 most 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
|
||||
[Fork a repo guide]: https://help.github.com/articles/fork-a-repo/
|
||||
[Contributing Guidelines]: #sec-guidelines
|
||||
[Create a Pull Request]: https://help.github.com/articles/creating-a-pull-request
|
||||
|
||||
To contribute to **nvf**, you'll first want to fork the repository. If you are
|
||||
new to Git and GitHub, do have a look at GitHub's [Fork a repo guide] for
|
||||
instructions on how you can do this. Once your fork is created, you should
|
||||
create a separate branch based on the most recent `main` branch. While you _can_
|
||||
work on the main branch of your repository, it is generally preferable to use
|
||||
feature branches. You should give your branch a reasonably descriptive name
|
||||
(e.g. `feature/new-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 fulfills our
|
||||
[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and
|
||||
[create a pull request](https://help.github.com/articles/creating-a-pull-request).
|
||||
[Contributing Guidelines], push the branch to GitHub and [Create 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.
|
||||
|
||||
Before submitting your pull request, please ensure that:
|
||||
|
||||
- The code is formatted as described in the formatting section
|
||||
- The commit message fits the contributing guidelines (**nvf** does not use
|
||||
Conventional Commits!)
|
||||
- You have updated the changelog entry and optionally updated the documentation
|
||||
with important information
|
||||
|
||||
None of those are reasons for a Pull Request to be closed, but it will reduce
|
||||
the number of roundtrips required before we can merge your Pull Request.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> If you do not agree with the idea of using Microsoft GitHub for contributions,
|
||||
> that is perfectly understandable. Unless you refuse to have your code hosted
|
||||
> on this platform, you may submit _patches_ through e-mail.
|
||||
>
|
||||
> You may send your patches to [@NotAShelf](https://github.com/notashelf) using
|
||||
> the public e-mail located on the GitHub page. Though, please remember to
|
||||
> adhere to the contributing guidelines strictly as e-mail instroduces a
|
||||
> significant overhead to the communication process.
|
||||
|
||||
## Guidelines {#sec-guidelines}
|
||||
|
||||
[discussions tab]: https://github.com/NotAShelf/nvf/discussions
|
||||
|
||||
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
|
||||
|
|
@ -48,34 +76,26 @@ 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.
|
||||
If you are not quite certain how those rules affect the change you are planning
|
||||
to make, then please start a friendly discussion in the [discussions tab] before
|
||||
you begin developing. This is not a requirement, but it might answer some of
|
||||
your burning questions and make the contribution process easier for all parties.
|
||||
|
||||
### Adding Documentation {#sec-guidelines-documentation}
|
||||
### Formatting {#sec-guidelines-formatting}
|
||||
|
||||
[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
|
||||
[code style section]: #sec-guidelines-code-style
|
||||
|
||||
Almost all changes warrant updates to the documentation: at the very least, you
|
||||
must update the changelog. Both the manual and module options use
|
||||
[Nixpkgs Flavoured Markdown].
|
||||
There are various files within the **nvf** repository. To maintain a sense of
|
||||
consistency and to avoid clashing opinions on how formatters should behave, we
|
||||
are very opinionated on how those files should be formatted.
|
||||
|
||||
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:
|
||||
- Nix files **must** be formatted with the Alejandra formatter, following some
|
||||
specific tips found in [Nix style section](#nix-sec-code-style-nix).
|
||||
- Markdown files **must** be formatted with the `deno fmt` command, as described
|
||||
in the [Markdown style section](#sec-code-style-markdown).
|
||||
|
||||
```console
|
||||
$ nix build .#docs-html
|
||||
$ 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] before
|
||||
your changes are submitted.
|
||||
|
||||
### Formatting Commits {#sec-guidelines-commit-message-style}
|
||||
|
||||
|
|
@ -98,27 +118,29 @@ The commit messages should follow the
|
|||
component or module in the first line. A commit message ideally, but not
|
||||
necessarily, follow the given template from home-manager's own documentation
|
||||
|
||||
```
|
||||
{component}: {description}
|
||||
```gitcommit
|
||||
{component}: {description}
|
||||
|
||||
{long description}
|
||||
{long description}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
[example commit message]: #sec-guidelines-ex-commit-message
|
||||
|
||||
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] 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)
|
||||
in home-manager contains the following commit message.
|
||||
[sample commit from Home Manager]: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
|
||||
|
||||
```
|
||||
The [sample commit from Home Manager] contains the following commit message.
|
||||
|
||||
```gitcommit
|
||||
starship: allow running in Emacs if vterm is used
|
||||
|
||||
The vterm buffer is backed by libvterm and can handle Starship prompts
|
||||
|
|
@ -128,30 +150,63 @@ without issues.
|
|||
Similarly, if you are contributing to **nvf**, you would include the scope of
|
||||
the commit followed by the description:
|
||||
|
||||
```
|
||||
```gitcommit
|
||||
languages/ruby: init module
|
||||
|
||||
Adds a language module for Ruby, adds appropriate formatters and Treesitter grammars
|
||||
Adds a language module for Ruby, adds appropriate formatters and Treesitter
|
||||
grammars
|
||||
```
|
||||
|
||||
Long description can be omitted if the change is too simple to warrant it. A
|
||||
minor fix in spelling or a formatting change does not warrant long description,
|
||||
however, a module addition or removal does as you would like to provide the
|
||||
relevant context, i.e. the reasoning behind it, for your commit.
|
||||
relevant context, i.e., the reasoning for your commit.
|
||||
|
||||
Finally, when adding a new module, say `modules/foo.nix`, we use the fixed
|
||||
commit format `foo: add module`. You can, of course, still include a long
|
||||
description if you wish.
|
||||
For new plugin additions, the following is a good starting point:
|
||||
|
||||
In case of nested modules, i.e `modules/languages/java.nix` you are recommended
|
||||
to contain the parent as well - for example `languages/java: some major change`.
|
||||
```gitcommit
|
||||
plugin: init
|
||||
```
|
||||
|
||||
You can, of course, still include a long description if you wish.
|
||||
|
||||
```gitcommit
|
||||
neotree: init
|
||||
|
||||
This adds the neo-tree plugin.
|
||||
```
|
||||
|
||||
In case of nested modules, e.g., `modules/languages/java.nix` you are
|
||||
recommended to contain the parent as well -- for example
|
||||
`languages/java: some major change` , or if it's a new language module,
|
||||
`languages/java: init`
|
||||
|
||||
### Code Style {#sec-guidelines-code-style}
|
||||
|
||||
#### 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.
|
||||
Across the tree, you're encouraged to follow kebab-case for file names, and keep
|
||||
text files (such as Markdown) to 80 characters or less. This 80 character
|
||||
recommendation also applies to option descriptions and string literals inside of
|
||||
Nix files.
|
||||
|
||||
#### Markdown {#sec-code-style-markdown}
|
||||
|
||||
Various Markdown files are used for documentation in the **nvf** repository.
|
||||
Besides the README, the manual is written almost entirely in Markdown. Since
|
||||
**nvf** uses a special variant of CommonMark, dubbed "Nixpkgs-flavored
|
||||
CommonMark" within this repository, you are encouraged to use the `deno fmt`
|
||||
command (provided by `pkgs.deno`) to format your Markdown sources. To avoid
|
||||
accidentally formatting HTML or CSS files, you might want to specify the file
|
||||
extension as follows:
|
||||
|
||||
```bash
|
||||
# Format all Markdown files within the repository
|
||||
$ deno fmt --ext md **/*.md
|
||||
```
|
||||
|
||||
You may also pass `--check` to the `deno fmt` command above to see if your
|
||||
formatting complies with the project standards.
|
||||
|
||||
#### Nix {#sec-code-style-nix}
|
||||
|
||||
|
|
@ -165,12 +220,16 @@ 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.
|
||||
|
||||
##### Attribute Sets
|
||||
|
||||
Please use one line code for attribute sets that contain only one subset. For
|
||||
example:
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
```nix
|
||||
# parent modules should always be unfolded
|
||||
# which means module = { value = ... } instead of module.value = { ... }
|
||||
# Parent modules should always be unfolded.
|
||||
# which means `module = { value = ... }` instead of `module.value = { ... }`.
|
||||
module = {
|
||||
value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
|
||||
|
||||
|
|
@ -190,23 +249,45 @@ module = {
|
|||
}
|
||||
```
|
||||
|
||||
<!-- markdownlint-enable MD013 -->
|
||||
|
||||
If you move a line down after the merge operator, Alejandra will automatically
|
||||
unfold the whole merged attrset for you, which we **do not** want.
|
||||
unfold the whole merged attribute set for you, which we **do not** want.
|
||||
|
||||
```nix
|
||||
module = {
|
||||
# This is wrong!
|
||||
key = mkEnableOption "some description" // {
|
||||
default = true; # we want this to be inline
|
||||
}; # ...
|
||||
};
|
||||
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
Though, if the right-hand side is more than a single line, it is okay to move to
|
||||
a new line. For example:
|
||||
|
||||
```nix
|
||||
module = {
|
||||
# This is okay!
|
||||
key = mkEnableOption "some description" // {
|
||||
default = true;
|
||||
example = false;
|
||||
};
|
||||
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
##### Lists
|
||||
|
||||
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.
|
||||
|
||||
```nix
|
||||
# this is ok
|
||||
# This is ok
|
||||
acceptableList = [
|
||||
item1 # comment
|
||||
item2
|
||||
|
|
@ -214,14 +295,14 @@ acceptableList = [
|
|||
item4
|
||||
];
|
||||
|
||||
# this is not ok
|
||||
# This is *not* ok
|
||||
listToBeAvoided = [item1 item2 /* comment */ item3 item4];
|
||||
|
||||
# this is ok
|
||||
# This is ok
|
||||
acceptableList = [item1 item2];
|
||||
|
||||
# this is also ok if the list is expected to contain more elements
|
||||
acceptableList= [
|
||||
# This is also ok if the list is expected to contain more elements
|
||||
acceptableList = [
|
||||
item1
|
||||
item2
|
||||
# more items if needed...
|
||||
|
|
@ -244,6 +325,81 @@ 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.
|
||||
|
||||
## Adding Documentation {#sec-guidelines-documentation}
|
||||
|
||||
[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
|
||||
[in-house documentation generator]: https://github.com/feel-co/ndg
|
||||
|
||||
Almost all changes to **nvf**'s codebase warrant updates to the documentation.
|
||||
At the very least, you must update the relevant changelog document to describe
|
||||
your changes. The documentation files found within the repository use a superset
|
||||
of [Nixpkgs Flavoured Markdown] thanks to our
|
||||
[in-house documentation generator].
|
||||
|
||||
As a general rule of thumb:
|
||||
|
||||
- Everything in the CommonMark spec is supported
|
||||
- Everything in Nixpkgs Flavoured Markdown is supported
|
||||
- Github Flavored Markdown is supported for Tables and Admonitions
|
||||
|
||||
By feeding NDG, our documentation generator, Markdown sources we can generate a
|
||||
HTML manual with various goodies, including a **search page** and an **options
|
||||
page**. The latter, found under `options.html` contains module options, similar
|
||||
to the official Nixpkgs search utility.
|
||||
|
||||
The HTML version of this documentation, dubbed the "nvf manual", can be
|
||||
generated and opened by typing the following in a shell within a clone of the
|
||||
**nvf** Git repository:
|
||||
|
||||
```sh
|
||||
# Build the online manual
|
||||
$ nix build .#docs-html
|
||||
|
||||
# Open it with a valid browser
|
||||
$ xdg-open $PWD/result/share/doc/nvf/index.html
|
||||
```
|
||||
|
||||
Additionally, if you are adding new links to the documentation it is **generally
|
||||
recommended** that you run the package that identifies dead URLs in the
|
||||
documentation:
|
||||
|
||||
```sh
|
||||
# Build the link checker package
|
||||
$ nix build .#docs-linkcheck
|
||||
```
|
||||
|
||||
You must ensure that the **HTML Documentation** builds before submitting a pull
|
||||
request.
|
||||
|
||||
### Formatting Changelog Entries
|
||||
|
||||
For additions, removals or any general change that concerns the users you must
|
||||
add a changelog entry. The changelog entries are later included in the rendered
|
||||
manual for users hoping to learn what has changed.
|
||||
|
||||
To maintain consistency, you must follow the following format in the changelog:
|
||||
|
||||
```markdown
|
||||
[<username>](https://github.com/<username>):
|
||||
|
||||
- Added ...
|
||||
- Removed ...
|
||||
- Changed ...
|
||||
```
|
||||
|
||||
```markdown
|
||||
# Release 0.9 {#sec-release-0-9}
|
||||
|
||||
## Breaking changes
|
||||
|
||||
- We broke everything, please migrate!
|
||||
```
|
||||
|
||||
If you are introducing _breaking_ changes to the repository, then you must also
|
||||
briefly mention what has changed in the breaking changes section of the
|
||||
changelog document that you are editing. If this section does not yet exist, you
|
||||
must create it.
|
||||
|
||||
## Keybinds {#sec-keybinds}
|
||||
|
||||
As of 0.4, there exists an API for writing your own keybinds and a couple of
|
||||
|
|
@ -252,7 +408,7 @@ useful utility functions are available in the
|
|||
following section contains a general overview to how you may utilize said
|
||||
functions.
|
||||
|
||||
## Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
|
||||
### Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
|
||||
|
||||
To set a mapping, you should define it in `vim.keymaps`.
|
||||
|
||||
|
|
@ -273,12 +429,12 @@ An example, simple keybinding, can look like this:
|
|||
```
|
||||
|
||||
There are many settings available in the options. Please refer to the
|
||||
[documentation](./options.html#option-vim-keymaps) to see a list of them.
|
||||
[documentation](/options.html#option-vim-keymaps) to see a list of them.
|
||||
|
||||
**nvf** provides a helper function, so that you don't have to write the mapping
|
||||
attribute sets every time:
|
||||
|
||||
- `mkKeymap`, which mimics neovim's `vim.keymap.set` function
|
||||
- `mkKeymap`, which mimics Neovim's `vim.keymap.set` function
|
||||
|
||||
You can read the source code of some modules to see them in action, but the
|
||||
usage should look something like this:
|
||||
|
|
@ -304,6 +460,8 @@ in {
|
|||
}
|
||||
```
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
||||
```nix
|
||||
# config.nix
|
||||
{
|
||||
|
|
@ -333,26 +491,29 @@ in {
|
|||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
<!-- markdownlint-enable MD013 -->
|
||||
|
||||
> [!TIP]
|
||||
> If you have come across a plugin that has an API that doesn't seem to easily
|
||||
> allow custom keybindings, don't be scared to implement a draft PR. We'll help
|
||||
> you get it done.
|
||||
|
||||
## Adding Plugins {#sec-additional-plugins}
|
||||
|
||||
There are two methods for adding new Neovim plugins to **nvf**. npins is the
|
||||
faster option that should be preferred if the plugin consists of pure Lua or
|
||||
Vimscript code. In which case there is no building required, and we can easily
|
||||
handle the copying of plugin files. Alternative method, which is required when
|
||||
plugins try to build their own libraries (e.g., in Rust or C) that need to be
|
||||
built with Nix to function correctly.
|
||||
**nvf** generally tries to avoid using Neovim plugins from Nixpkgs, and thus
|
||||
uses one of the two alternative methods where applicable. npins is the faster
|
||||
option that should be preferred if the plugin consists of pure Lua or Vimscript
|
||||
code. In which case there is no building required, and we can easily handle the
|
||||
copying of plugin files. Alternative method, which is required when plugins try
|
||||
to build their own libraries (e.g., in Rust, C or even Assembly) that need to be
|
||||
built with Nix to function correctly. In this case you must use a local overlay.
|
||||
|
||||
### With npins {#sec-npins-for-plugins}
|
||||
|
||||
npins is the standard method of adding new plugins to **nvf**. You simply need
|
||||
the repository URL for the plugin, and can add it as a source to be built
|
||||
automatically with one command. To add a new Neovim plugin, use `npins`. For
|
||||
example:
|
||||
npins is the standard, and as described above, the _faster_ method of adding new
|
||||
plugins to **nvf**. You simply need the repository URL for the plugin, and you
|
||||
can add it as a source to be built automatically with just one command. To add a
|
||||
new Neovim plugin, use `npins`. For example:
|
||||
|
||||
```bash
|
||||
nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
|
||||
|
|
@ -364,16 +525,13 @@ Then run:
|
|||
npins add --name <plugin name> github <owner> <repo> -b <branch>
|
||||
```
|
||||
|
||||
::: {.note}
|
||||
|
||||
Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
|
||||
example
|
||||
|
||||
```bash
|
||||
npins add --name lazydev-nvim github folke lazydev.nvim -b main
|
||||
```
|
||||
|
||||
:::
|
||||
> [!NOTE]
|
||||
> Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
|
||||
> example
|
||||
>
|
||||
> ```bash
|
||||
> npins add --name lazydev-nvim github folke lazydev.nvim -b main
|
||||
> ```
|
||||
|
||||
Once the `npins` command is done, you can start referencing the plugin as a
|
||||
**string**.
|
||||
|
|
@ -399,15 +557,21 @@ We use `buildRustPackage` to build the library from the repository root, and
|
|||
copy everything in the `postInstall` phase.
|
||||
|
||||
```nix
|
||||
postInstall = ''
|
||||
cp -r {lua,plugin} "$out"
|
||||
{
|
||||
# ...
|
||||
|
||||
postInstall = ''
|
||||
cp -r {lua,plugin} "$out"
|
||||
|
||||
mkdir -p "$out/doc"
|
||||
cp 'doc/'*'.txt' "$out/doc/"
|
||||
mkdir -p "$out/doc"
|
||||
cp 'doc/'*'.txt' "$out/doc/"
|
||||
|
||||
mkdir -p "$out/target"
|
||||
mv "$out/lib" "$out/target/release"
|
||||
'';
|
||||
mkdir -p "$out/target"
|
||||
mv "$out/lib" "$out/target/release"
|
||||
'';
|
||||
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs
|
||||
|
|
@ -503,7 +667,7 @@ own fields!
|
|||
}
|
||||
```
|
||||
|
||||
### Details of toLuaObject {#sec-details-of-toluaobject}
|
||||
### Details of `toLuaObject` {#sec-details-of-toluaobject}
|
||||
|
||||
As you've seen above, `toLuaObject` is used to convert our nix attrSet
|
||||
`cfg.setupOpts`, into a lua table. Here are some rules of the conversion:
|
||||
|
|
@ -544,7 +708,7 @@ As you've seen above, `toLuaObject` is used to convert our nix attrSet
|
|||
}
|
||||
```
|
||||
|
||||
### Lazy plugins {#sec-lazy-plugins}
|
||||
### Lazy Loading Plugins {#sec-lazy-plugins}
|
||||
|
||||
If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it.
|
||||
Lazy plugins are managed by `lz.n`.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Introduction {#nvf-manual}
|
||||
|
||||
Version @NVF_VERSION@
|
||||
Generated for nvf @NVF_VERSION@
|
||||
|
||||
## Preface {#ch-preface}
|
||||
|
||||
|
|
@ -8,11 +8,11 @@ Version @NVF_VERSION@
|
|||
|
||||
**nvf** is a highly modular, configurable, extensible and easy to use Neovim
|
||||
configuration framework built and designed to be used with Nix. Boasting
|
||||
flexibility, robustness and ease of use, this projecct allows you to configure a
|
||||
flexibility, robustness and ease of use, this project allows you to configure a
|
||||
fully featured Neovim instance with a few lines of Nix with lots of options for
|
||||
advanced users as well.
|
||||
|
||||
## Try it out {#ch-try-it-out}
|
||||
## Try it Out {#ch-try-it-out}
|
||||
|
||||
Thanks to the portability of Nix, you can try out nvf without actually
|
||||
installing it to your machine. Below are the commands you may run to try out
|
||||
|
|
@ -27,20 +27,27 @@ You may try out any of the provided configurations using the `nix run` command
|
|||
on a system where Nix is installed.
|
||||
|
||||
```sh
|
||||
# Add the nvf cache
|
||||
$ cachix use nvf # Optional: it'll save you CPU resources and time
|
||||
|
||||
# Run the minimal configuration with the cache enabled
|
||||
$ nix run github:notashelf/nvf#nix # Will run the default minimal configuration
|
||||
```
|
||||
|
||||
Do keep in mind that this is **susceptible to garbage collection** meaning that
|
||||
the built outputs will be removed from your Nix store once you garbage collect.
|
||||
|
||||
## Using Prebuilt Configs {#sec-using-prebuilt-configs}
|
||||
## Using Prebuilt Configurations {#sec-using-prebuilt-configs}
|
||||
|
||||
<!-- markdownlint-disable MD014 -->
|
||||
|
||||
```bash
|
||||
$ nix run github:notashelf/nvf#nix
|
||||
$ nix run github:notashelf/nvf#maximal
|
||||
```
|
||||
|
||||
<!-- markdownlint-enable MD014 -->
|
||||
|
||||
### Available Configurations {#sec-available-configs}
|
||||
|
||||
> [!NOTE]
|
||||
|
|
@ -61,7 +68,7 @@ $ nix run github:notashelf/nvf#nix test.nix
|
|||
```
|
||||
|
||||
This command will start Neovim with some opinionated plugin configurations, and
|
||||
is designed specifically for Nix. the `nix` configuration lets you see how a
|
||||
is designed specifically for Nix. The `nix` configuration lets you see how a
|
||||
fully configured Neovim setup _might_ look like without downloading too many
|
||||
packages or shell utilities.
|
||||
|
||||
|
|
@ -87,12 +94,16 @@ companion or fun plugins.
|
|||
|
||||
## Installing nvf {#ch-installation}
|
||||
|
||||
<!-- markdownlint-disable MD051 -->
|
||||
|
||||
[module installation section]: #ch-module-installation
|
||||
|
||||
There are multiple ways of installing nvf on your system. You may either choose
|
||||
the standalone installation method, which does not depend on a module system and
|
||||
may be done on any system that has the Nix package manager or the appropriate
|
||||
modules for NixOS and home-manager as described in the
|
||||
<!-- markdownlint-enable MD051 -->
|
||||
|
||||
There are multiple ways of installing **nvf** on your system. You may either
|
||||
choose the standalone installation method, which does not depend on a module
|
||||
system and may be done on any system that has the Nix package manager or the
|
||||
appropriate modules for NixOS and Home Manager as described in the
|
||||
[module installation section].
|
||||
|
||||
```{=include=}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue