From a196e9610f0dec12e681fee2eeb86ecf73e144df Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Mon, 25 Nov 2024 19:16:46 +0300 Subject: [PATCH] docs: format via `deno fmt` This should be a pre-commit hook in the future. --- docs/manual/configuring/custom-plugins.md | 14 ++-- docs/manual/configuring/dag-entries.md | 6 +- docs/manual/configuring/dags.md | 68 ++++++++--------- docs/manual/configuring/languages.md | 10 +-- docs/manual/configuring/languages/lsp.md | 4 +- docs/manual/default-configs.md | 5 +- docs/manual/default-configs/maximal.md | 6 +- docs/manual/hacking/getting-started.md | 21 +++--- docs/manual/hacking/guidelines.md | 89 ++++++++++++----------- docs/manual/hacking/testing.md | 4 +- docs/release-notes/release-notes.md | 4 +- 11 files changed, 114 insertions(+), 117 deletions(-) diff --git a/docs/manual/configuring/custom-plugins.md b/docs/manual/configuring/custom-plugins.md index 76b32ea..b2c8474 100644 --- a/docs/manual/configuring/custom-plugins.md +++ b/docs/manual/configuring/custom-plugins.md @@ -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 diff --git a/docs/manual/configuring/dag-entries.md b/docs/manual/configuring/dag-entries.md index ff5d5c7..88c580b 100644 --- a/docs/manual/configuring/dag-entries.md +++ b/docs/manual/configuring/dag-entries.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, diff --git a/docs/manual/configuring/dags.md b/docs/manual/configuring/dags.md index 6bcd156..3435182 100644 --- a/docs/manual/configuring/dags.md +++ b/docs/manual/configuring/dags.md @@ -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` -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` -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` -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` -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` -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` -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,13 +137,13 @@ foo.bar = { > `lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag` -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 = - { b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ]; +foo.bar = + { b = 0; } // lib.dag.entriesBefore "a" [ "b" ] [ 1 2 ]; ``` is equivalent to @@ -163,10 +160,9 @@ foo.bar = { > `lib.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag` -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 = diff --git a/docs/manual/configuring/languages.md b/docs/manual/configuring/languages.md index 0e54342..7471436 100644 --- a/docs/manual/configuring/languages.md +++ b/docs/manual/configuring/languages.md @@ -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 diff --git a/docs/manual/configuring/languages/lsp.md b/docs/manual/configuring/languages/lsp.md index b7a9d07..6d6ed5b 100644 --- a/docs/manual/configuring/languages/lsp.md +++ b/docs/manual/configuring/languages/lsp.md @@ -1,8 +1,8 @@ # LSP Custom Packages/Command {#sec-languages-custom-lsp-packages} In any of the `opt.languages..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: diff --git a/docs/manual/default-configs.md b/docs/manual/default-configs.md index 60f3d69..96ffa81 100644 --- a/docs/manual/default-configs.md +++ b/docs/manual/default-configs.md @@ -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 diff --git a/docs/manual/default-configs/maximal.md b/docs/manual/default-configs/maximal.md index 49f9569..3688763 100644 --- a/docs/manual/default-configs/maximal.md +++ b/docs/manual/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. ::: diff --git a/docs/manual/hacking/getting-started.md b/docs/manual/hacking/getting-started.md index 72927dc..9f1df74 100644 --- a/docs/manual/hacking/getting-started.md +++ b/docs/manual/hacking/getting-started.md @@ -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. diff --git a/docs/manual/hacking/guidelines.md b/docs/manual/hacking/guidelines.md index e0afe25..c43ceb9 100644 --- a/docs/manual/hacking/guidelines.md +++ b/docs/manual/hacking/guidelines.md @@ -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 diff --git a/docs/manual/hacking/testing.md b/docs/manual/hacking/testing.md index 10830b6..47b8a1c 100644 --- a/docs/manual/hacking/testing.md +++ b/docs/manual/hacking/testing.md @@ -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. diff --git a/docs/release-notes/release-notes.md b/docs/release-notes/release-notes.md index 4f896aa..daeb03e 100644 --- a/docs/release-notes/release-notes.md +++ b/docs/release-notes/release-notes.md @@ -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