diff --git a/.github/README.md b/.github/README.md new file mode 100644 index 00000000..fa4aefa7 --- /dev/null +++ b/.github/README.md @@ -0,0 +1,150 @@ +# Hjem Rum \[ˈjɛmˀ ˈʁɔmˀ\][^1] + +[Hjem]: https://github.com/feel-co/hjem +[Danish IPA]: https://en.wikipedia.org/wiki/Help:IPA/Danish +[source]: https://github.com/snugnug/hjem-rum/tree/main/modules/collection +[discussions]: https://github.com/snugnug/hjem-rum/discussions +[documentation]: https://rum.snugnug.org +[our docs]: https://rum.snugnug.org/contributing/introduction.html +[@NotAShelf]: https://github.com/NotAShelf +[@éclairevoyant]: https://github.com/eclairevoyant +[contributors]: https://github.com/snugnug/hjem-rum/graphs/contributors +[Home Manager]: https://github.com/nix-community/home-manager +[GPLv3]: https://www.gnu.org/licenses/gpl-3.0.en.html +[license at the top level of our codebase]: https://github.com/snugnug/hjem-rum/blob/main/LICENSE +[CC-BY-NC-SA 4.0]: https://creativecommons.org/licenses/by-nc-sa/4.0/ +[license within the documentation directory]: https://github.com/snugnug/hjem-rum/blob/main/docs/manual/LICENSE + +A module collection for managing your `$HOME` with [Hjem]. + +[^1]: Please see Wikipedia's article on [Danish IPA]. Alternatively, a rough + English phonetic transcription would be _Yem Room_, with _room_ pronounced a + bit closer to _rawm_. + +## A brief explanation + +> [!WARNING] +> Hjem Rum is currently considered alpha software―here be dragons. While many of +> us currently use its modules in our NixOS configurations, that does not mean +> it will necessarily offer a seamless experience yet, nor does it mean there +> will not be breaking changes (there will). As Hjem Rum continues to grow and +> evolve, it should become more stable and expansive, but please be patient as +> it is a hobby project. Furthermore, Hjem, the tooling Hjem Rum is built off +> of, is still unfinished and missing critical features, such as services. Hjem +> Rum is still useable, but it is not for the novice user. + +Built off the Hjem tooling, Hjem Rum (loosely translated to "rooms of a home") +is a collection of modules for various applications intended to simplify `$HOME` +management for usage and configuration of applications. + +Hjem was initially created as a streamlined implementation of the `home` +functionality that Home Manager provides. Hjem Rum, in contrast, is intended to +provide an expansive module collection as a useful abstraction for users to +configure their applications with ease, recreating Home Manager's complete +functionality. + +## Frequently Asked Questions (FAQ) + +Have any questions? Please read ahead. + +**Q.** Is Hjem just a cleaner Home Manager? + +**A.** You can think of Hjem as "Home Manager without modules." It is also a +cleaner implementation yes. The decision to make Hjem "Home Manager without +modules" was done for two reasons: firstly, in order to reduce evaluation times +for the core toolset. When using Hjem by itself, evaluation/build time is much +less than using Home Manager, since the entire module collection does not need +to be evaluated. The second reason was to streamline the implementation. Because +Hjem is _just_ the management of user files and services, it is easier to +optimize the implementation and continue maintenance, without the overhead of +the entire module collection sharing the same repository. Ultimately, Hjem +leaving out the modules makes it lighter for both users and developers. + +**Q.** So then why does Hjem Rum exist? + +**A.** Hjem Rum exists to fill the gap that Hjem leaves in $HOME management. +While the bare implementation that Hjem provides is useful for those that have +an intimate understanding of NixOS, the average user needs a cleaner, more user +friendly interface between NixOS and Hjem. If Hjem is "Home Manager without +modules," Hjem Rum are the modules that are added on top of Hjem. This means +easy to use options like `programs.alacritty.enable` and +`programs.alacritty.settings` that automatically install the program, configure +it to your liking, and integrate it into other programs you manage with Hjem +Rum. + +**Q.** If Hjem Rum just adds the modules back, why would I use it instead of +Home Manager? + +**A.** Hjem Rum was built from the ground up with more sane and unopinionated +practices and defaults, intending to minimize overhead and streamline the +codebase, even at the cost of development time. The goal of Hjem Rum is to +minimize technical debt and produce something that uses the optimized Hjem to +manage $HOME in a much cleaner fashion that makes it more maintainable in the +long term. Just as Hjem's lack of modules allows its implementation to be +streamlined, we hope that Hjem Rum's distance from the underlying toolset allows +its implementation to be similarly streamlined. Furthermore, if Hjem is brought +into Nixpkgs, Hjem Rum can easily serve as an external module set, not further +bloating Nixpkgs, without requiring extensive refactoring. + +**Q.** What if I don't want the modules? + +**A.** If you don't want to use our supplied modules and instead write your own +or even forgo wrapping `files` and `packages` entirely, we strongly encourage +you to just use Hjem on its own! If that route interests you, we also encourage +you to take a look through this repository to view the [source] of Hjem Rum's +modules. You can certainly learn a lot from our code, even if you do not wish to +use it. + +**Q.** Okay, you've sold me. Is there an easy way to migrate from Home Manager +to Hjem Rum? + +**A.** Unfortunately, there is no shortcut―you'll have to do it manually. +However, because Hjem Rum's API is not too different from Home Manager's, it is +thankfully not too difficult. The most burdensome part would be moving your +module configuration from Home Manager modules into your NixOS or Hjem Modules, +and changing the names of the option calls. + +**Q.** Do you support Darwin/Standalone? + +**A.** The question of supporting Nix Darwin and Standalone is more a matter of +what Hjem supports. At the moment, Hjem supports neither Darwin nor Standalone, +and so Hjem Rum does not either. However, both are on the table for the +development of Hjem, and Hjem Rum would follow suit if compatibility was added. + +_Still_ confused? Go ahead and leave a question in [discussions]. + +## Usage and Documentation + +Hjem Rum includes a full set of documentation, including an options search +system. Please see our [documentation] for both guides on installing Hjem Rum +and a full list of options that you can configure programs with. + +## Contribution + +If you are interested in contributing to Hjem Rum, please check out our +contributing guidelines on [our docs]. We are always interested in +contributions, particularly as Hjem Rum is a project with an inherently enormous +scope. If you are new, unfamiliar, or otherwise scared of trying to contribute, +please know that any contribution helps, big or small, and that reviewers are +here to help you contribute and write good code for this project. + +## Credits + +Credit goes to [@NotAShelf] and [@éclairevoyant] for creating Hjem. + +We would also like to give special thanks to all [contributors], past and +present, for making Hjem Rum what it is today. + +Additionally, we would like to thank everyone who has contributed or maintained +[Home Manager], as without them, this project likely would not be possible, or +even be conceived. + +## Licenses + +All the code within this repository is protected under the [GPLv3] license +unless explicitly stated otherwise within a file. Please see the +[license at the top level of our codebase] for more information. + +Additionally, all of our documentation, including this file, is protected under +[CC-BY-NC-SA 4.0], as according to the +[license within the documentation directory]. diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 00000000..08df5d58 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,43 @@ +name: "Docs Check" +permissions: read-all + +on: + pull_request: + branches: + - main + path: + - modules/collection/** + - modules/lib/** + - docs/** + - flake.nix + - flake.lock + - .github/workflows/docs-check.yml + +jobs: + docs-check: + name: "Test build docs" + runs-on: ubuntu-latest + + steps: + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@main + + - name: Checkout + uses: actions/checkout@v4 + + - name: Build documentation packages + run: nix build .#docs -Lv + + lychee-check: + name: "Link checker" + runs-on: ubuntu-latest + + steps: + - name: Install Nix + uses: DeterminateSystems/nix-installer-action@main + + - name: Checkout + uses: actions/checkout@v4 + + - name: Build documentation packages + run: nix build .#docsLinkCheck -Lv diff --git a/README.md b/README.md deleted file mode 100644 index 4226b07e..00000000 --- a/README.md +++ /dev/null @@ -1,178 +0,0 @@ -# Hjem Rum - -[Hjem]: https://github.com/feel-co/hjem -[contributing guidelines]: ./docs/CONTRIBUTING.md -[license]: LICENSE -[programs/fish]: modules/collection/programs/fish.nix -[programs/zsh]: modules/collection/programs/zsh.nix -[programs/nushell]: modules/collection/programs/nushell.nix -[desktops/hyprland]: modules/collection/desktops/hyprland.nix -[#17]: https://github.com/snugnug/hjem-rum/issues/17 -[#120]: https://github.com/snugnug/hjem-rum/pull/120 -[@eclairevoyant]: https://github.com/eclairevoyant -[@NotAShelf]: https://github.com/NotAShelf -[documentation]: https://snugnug.github.io/hjem-rum/ - -A module collection for managing your `$HOME` with [Hjem]. - -## A brief explanation - -> [!IMPORTANT] -> Hjem, the tooling Hjem Rum is built off of, is still unfinished. Use at your -> own risk, and beware of bugs, issues, and missing features. If you do not feel -> like being a beta tester, wait until Hjem is more finished. It is not yet -> ready to fully replace Home Manager in the average user's config, but if you -> truly want to, an option could be to use both in conjunction. Either way, as -> Hjem continues to be developed, Hjem Rum will be worked on as we build modules -> and functionality out to support average users. - -Based on the Hjem tooling, Hjem Rum (literally meaning "home rooms") is a -collection of modules for various programs and services to simplify the use of -Hjem for managing your `$HOME` files. - -Hjem was initially created as an improved implementation of the `home` -functionality that Home Manager provides. Its purpose was minimal. Hjem Rum's -purpose is to create a module collection based on that tooling in order to -recreate the functionality that Home Manager's large collection of modules -provides, allowing you to simply install and config a program. - -## Setup - -> [!IMPORTANT] -> [#120] introduces breaking changes, as we now use `xdg.config.files` in our -> modules. If you are getting errors related to the option not existing, please -> update your flake's Hjem input. - -To start using Hjem Rum, you must first import the flake and its modules into -your system(s): - -```nix -# flake.nix -inputs = { - nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; - hjem = { - url = "github:feel-co/hjem"; - # You may want hjem to use your defined nixpkgs input to - # minimize redundancies. - inputs.nixpkgs.follows = "nixpkgs"; - }; - hjem-rum = { - url = "github:snugnug/hjem-rum"; - # You may want hjem-rum to use your defined nixpkgs input to - # minimize redundancies. - inputs.nixpkgs.follows = "nixpkgs"; - # Same goes for hjem, to avoid discrepancies between the version - # you use directly and the one hjem-rum uses. - inputs.hjem.follows = "hjem"; - }; -}; - -# One example of importing the module into your system configuration -outputs = { - self, - nixpkgs, - ... -} @ inputs: { - nixosConfigurations = { - default = nixpkgs.lib.nixosSystem { - specialArgs = {inherit inputs;}; - modules = [ - # Import the hjem module - inputs.hjem.nixosModules.default - # Whatever other modules you are importing - ]; - }; - }; -} -``` - -Be sure to first set the necessary settings for Hjem and import the Hjem module -from the input: - -```nix -# configuration.nix -hjem = { - # Importing the modules - extraModules = [ - inputs.hjem-rum.hjemModules.default - ]; - # Configuring your user(s) - users. = { - enable = true; - directory = "/home/"; - user = ""; - }; - # You should probably also enable clobberByDefault at least for now. - clobberByDefault = true; -}; -``` - -You can then configure any of the options defined in this flake in any nix -module: - -```nix -# configuration.nix -hjem.users..rum.programs.alacritty = { - enable = true; - #package = pkgs.alacritty; # Default - settings = { - window = { - dimensions = { - lines = 28; - columns = 101; - }; - padding = { - x = 6; - y = 3; - }; - }; - }; -} -``` - -> [!TIP] -> Consult the [documentation] for an overview of all available options. - -## Environmental Variables - -Hjem provides attribute set "environment.sessionVariables" that allows the user -to set environmental variables to be sourced. However, Hjem does not have the -capability to actually source them. This can be done manually, which is what -Hjem Rum tries to do. - -Currently, some of our modules may add environmental variables (such as our GTK -module), but cannot load them without the use of another module. Currently, -modules that load environmental variables include: - -- [programs/fish] -- [programs/zsh] -- [programs/nushell] -- [desktops/hyprland] - -If you are either using something like our GTK module, or are manually adding -variables to `environment.sessionVariables`, but are neither loading those -variables manually, or using one of the above modules, those variables will not -be loaded, and may cause unintended problems. For example, GTK applications may -not respect your theme, as some rely on the environmental variable to actually -use the theme you declare. - -Please see [#17] for status on providing support for shells and compositors. If -your shell or compositor is on listed there, please leave a comment and it will -be added. You are encouraged to open a PR to help support your shell or -compositor if possible. - -## Contributing - -Hjem Rum is always in need of contribution. Please see our -[contributing guidelines] for more information on how to contribute and our -guidelines. - -## Credits - -Credit goes to [@NotAShelf] and [@eclairevoyant] for creating Hjem. - -## License - -All the code within this repository is protected under the GPLv3 license unless -explicitly stated otherwise within a file. Please see [LICENSE] for more -information. diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..2be88e83 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +rum.snugnug.org diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index 81c203eb..00000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1,386 +0,0 @@ -# Contributing - -[commitizen]: https://github.com/commitizen-tools/commitizen -[article from GeeksforGeeks]: https://www.geeksforgeeks.org/how-to-create-a-new-branch-in-git/ -[creating a PR]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request -[documentation on forking repositories]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo -[documentation on reviewing PRs]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request -[Core Principles]: #core-principles -[REVIEWING.md]: ./REVIEWING.md - -Hjem Rum (or HJR) is always in need of contributions as a module collection. As -programs are developed, modules will need to be added, changed, removed, etc., -meaning that the development of HJR is, in essence, unending. - -Contributing is also a great way to learn the Nix module system and even -function writing. Don't be afraid to experiment and try learning something new. - -If you are familiar with contributing to open source software, you can safely -skip ahead to [Core Principles]. Otherwise, read the following section to learn -how to fork a repo and open a PR. - -## Getting Started - -To begin contributing to HJR, you will first need to create a fork off of the -main branch in order to make changes. For info on how to do this, we recommend -GitHub's own [documentation on forking repositories]. - -Once you have your own fork, it is recommend that you create a branch for the -changes or additions you seek to make, to make it easier to set up multiple PRs -from your fork. To do so, you can read this [article from GeeksforGeeks] that -will also explain branches for you. Don't worry too much about the technical -details, the most important thing is to make and switch to a branch from HEAD. - -### Commit format - -> [!TIP] -> Our dev shell allows for interactive commits, through the means of -> [commitizen]. If this is preferred, you can run `cz commit` to be prompted to -> build your commit. - -For consistency, we do enforce a strict (but simple) commit style, that will be -linted against. The format is as follows (sections between `[]` are optional): - -```console -/[]: - -[] -``` - -- \: the main scope of your commit. If making a change to a - program, this would be `programs`). For changes unrelated to the modules API, - we tend to use semantic scopes such as `meta` for CI/repo related changes. - -- \[\]: An optional, more specific scope for your module. If - making changes to a specific program, this would be `programs/foot`. - -- \: A free form commit message. Needs to be imperative and without - punctuation (e.g. `do stuff` instead of `did stuff.`). - -- \[\]: A free form commit body. Having one is encouraged when your - changes are difficult to explain, unless you're writing in-depth code comments - (it is still preferred however). - -You can now make your changes in your editor of choice. After committing your -changes, you can run: - -```shell -git push origin -``` - -and then open up a PR, or "Pull Request," in the upstream HJR repository. Again, -GitHub has good documentation for [creating a PR]. - -After you have setup a PR, it will be [reviewed](#reviewing-a-pr) by maintainers -and changes may be requested. Make the changes requested and eventually it will -likely be accepted and merged into main. - -## Core Principles - -In creating HJR, we had a few principles in mind for development: - -1. Minimize the number of options written; -1. Include only the module collection - leave functionality to Hjem; and -1. Maintain readability of code, even for new users. - -Please keep these in mind as you read through our general guidelines for -contributing. - -## Guidelines - -These guidelines, are, of course, merely guidelines. There are and will continue -to be exceptions. However, do your best to stick to them, and keep in mind that -reviewers will hold you to them as much as possible. - -### Where to put a new module - -WIP - -### Aliases - -At the top of any module, there should always be a `let ... in` set. Within -this, functions should have their location aliased, cfg should be aliased, and -any generators should have an alias as well. Here's an example for a module that -makes use of the TOML generator used in nixpkgs: - -```nix -{ - config, - lib, - pkgs, - ... -}: let - # in case you are unfamiliar, 'inherit func;' is the same as 'func = func;', and - # 'inherit (cfg) func;' is the same as 'func = cfg.func;' - inherit (lib.modules) mkIf; - inherit (lib.options) mkOption mkEnableOption mkPackageOption; - - toml = pkgs.formats.toml {}; - - cfg = config.rum.programs.alacritty; -in { - options.rum.programs.alacritty = { -``` - -Notice that each function has its location aliased with an inherit to its target -location. Ideally, this location should be where one could find it in the source -code. For example, rather than using `lib.mkIf`, we use `lib.modules.mkIf`, -because mkIf is declared at `lib/modules.nix` within the nixpkgs repo. - -Also notice that in this case, `pkgs.formats.toml {}` includes both `generate` -and `type`, so the alias name is just `toml`. - -Always be sure to include `cfg` that links to the point where options are -configured by the user. - -### Writing Options - -> [!IMPORTANT] -> When writing options for any Nix module, do NOT make any option depend on a -> value from `config`. Options should be pure, or it will interfere with modules -> evaluation. - -Writing new options is the core of any new module. It is also the easiest place -to blunder. As stated above, a core principle of HJR is to minimize the number -of options as much as possible. As such, we have created a general template that -should help inform you of what options are needed and what are not: - -- `enable`: Used to toggle install and configuration of package(s). -- `package`: Used to customize and override the package installed. - - As needed, `packages`: List of packages used in a module. -- `settings`: Primary configuration option, takes Nix code and converts to - target lang. - - As needed, one extra option for each extra file, such as `theme` for - theme.toml. -- As needed, `extraConfig`: Extra lines of strings passed directly to config - file for certain programs. - -For the most part, this should be sufficient. Overrides of packages should be -simply offered through a direct override in `package`. For example, ncmpcpp's -package has a `withVisualizer ? false` argument. Rather than creating an extra -option for this, the contributor should note this with `extraDescription` like -so: - -```nix -options.rum.programs.ncmpcpp = { - enable = mkEnableOption "ncmpcpp, a mpd-based music player."; - - package = mkPackageOption pkgs "ncmpcpp" { - extraDescription = '' - You can use an override to toggle certain features like the visualizer, a clock screen, and more. - Please check out the package source for a complete list. - ''; - }; -``` - -and the user could simply pass: - -```nix -config.hjem.users..rum.programs.ncmpcpp = { - enable = true; - package = (pkgs.ncmpcpp.override { - withVisualizer = true; - }); -}; -``` - -The `type` of `settings` and other conversion options should preferably be a -`type` option exposed by the generator (for example, TOML has -`pkgs.formats.toml {}.type` and `pkgs.formats.toml {}.generate`), or, if using a -custom generator, a `type` should be created in `lib/types/` (for example, -`hyprType`). Otherwise, a simple `attrsOf anything` would suffice. - -As a rule of thumb, submodules should not be employed. Instead, there should -only be one option per file. For some files, such as spotify-player's -`keymap.toml`, you may be tempted to create multiple options for `actions` and -`keymaps`, as Home Manager does. Please avoid this. In this case, we can have a -simple `keymap` option that the user can then include a list of keymaps and/or a -list of actions that get propagated accordingly: - -```nix - keymap = mkOption { - type = toml.type; - default = {}; - example = { - keymaps = [ - { - command = "NextTrack"; - key_sequence = "g n"; - } - ]; - actions = [ - { - action = "GoToArtist"; - key_sequence = "g A"; - } - ]; - }; - description = '' - Sets of keymaps and actions converted into TOML and written to - {file}`$HOME/.config/spotify-player/keymap.toml`. - See example for how to format declarations. - - Please reference https://github.com/aome510/spotify-player/blob/master/docs/config.md#keymaps - for more information. - ''; - }; -``` - -Also note that the option description includes a link to upstream info on -settings options. - -### Conditional Config - -Always use a `mkIf` before the config section. Example: - -```nix -config = mkIf cfg.enable { - -}; -``` - -As a general guideline, **do not write empty strings to files**. Not only is -this poorly optimized, but it will cause issues if a user happens to be manually -using the Hjem tooling alongside HJR. Here are some examples of how you might -avoid this: - -```nix -config = mkIf cfg.enable { - packages = [cfg.package]; - files.".config/alacritty/alacritty.toml".source = mkIf (cfg.settings != {}) ( - toml.generate "alacritty.toml" cfg.settings - ); -}; -``` - -Here all that is needed is a simple `mkIf` with a condition of the `settings` -option not being left empty. In a case where you write to multiple files, you -can use `optionalAttrs`, like so: - -```nix -files = ( - optionalAttrs (cfg.settings != {}) { - ".gtkrc-2.0".text = toGtk2Text {inherit (cfg) settings;}; - ".config/gtk-3.0/settings.ini".text = toGtkINI {Settings = cfg.settings;}; - ".config/gtk-4.0/settings.ini".text = toGtkINI {Settings = cfg.settings;}; - } - // optionalAttrs (cfg.css.gtk3 != "") { - ".config/gtk-3.0/gtk.css".text = cfg.css.gtk3; - } - // optionalAttrs (cfg.css.gtk4 != "") { - ".config/gtk-4.0/gtk.css".text = cfg.css.gtk4; - } -); -``` - -This essentially takes the attrset of `files` and _optionally_ adds attributes -defining more files to be written to _if_ the corresponding option has been set. -This is optimal because the first three files written to share an option due to -how GTK configuration works. - -One last case is in the Hyprland module, where several checks and several -options are needed to compile into one file. Here is how it is done: - -```nix -files = let - check = { - plugins = cfg.plugins != []; - settings = cfg.settings != {}; - variables = { - noUWSM = config.environment.sessionVariables != {} && !osConfig.programs.hyprland.withUWSM; - withUWSM = config.environment.sessionVariables != {} && osConfig.programs.hyprland.withUWSM; - }; - extraConfig = cfg.extraConfig != ""; - }; -in { - ".config/hypr/hyprland.conf".text = mkIf (check.plugins || check.settings || check.variables.noUWSM || check.extraConfig) ( - optionalString check.plugins (pluginsToHyprconf cfg.plugins cfg.importantPrefixes) - + optionalString check.settings (toHyprconf { - attrs = cfg.settings; - inherit (cfg) importantPrefixes; - }) - + optionalString check.variables.noUWSM (toHyprconf { - attrs.env = - # https://wiki.hyprland.org/Configuring/Environment-variables/#xdg-specifications - [ - "XDG_CURRENT_DESKTOP,Hyprland" - "XDG_SESSION_TYPE,wayland" - "XDG_SESSION_DESKTOP,Hyprland" - ] - ++ mapAttrsToList (key: value: "${key},${value}") config.environment.sessionVariables; - }) - + optionalString check.extraConfig cfg.extraConfig - ); - - /* - uwsm environment variables are advised to be separated - (see https://wiki.hyprland.org/Configuring/Environment-variables/) - */ - ".config/uwsm/env".text = - mkIf check.variables.withUWSM - (toEnvExport config.environment.sessionVariables); - - ".config/uwsm/env-hyprland".text = let - /* - this is needed as we're using a predicate so we don't create an empty file - (improvements are welcome) - */ - filteredVars = - filterKeysPrefixes ["HYPRLAND_" "AQ_"] config.environment.sessionVariables; - in - mkIf (check.variables.withUWSM && filteredVars != {}) - (toEnvExport filteredVars); -}; -``` - -An additional attrset of boolean aliases is set within a `let ... in` set to -highlight the different checks done and to add quick ways to reference each -check without excess and redundant code. - -First, the file is only written if any of the options to write to the file are -set. `optionalString` is then used to compile each option's results in an -optimized and clean way. - -### Extending Lib - -Rather than having functions scattered throughout the module collection, we -would rather keep our directories organized and purposeful. Therefore, all -custom functions should go into our extended lib, found at `modules/lib/`. - -The most common functions that might be created are a `generator` and `type` -pair. The former should be prefixed with "to" to maintain style and describe -their function: conversion _to_ other formats. For example, `toNcmpcppSettings` -is the function that converts to the format required for ncmpcpp settings. - -Likewise, types should be suffixed with "Type" to maintain style and describe -their function. For example, `hyprType` describes the type used in `settings` -converted to hyprlang. - -When it comes to directory structure, you should be able to infer how we -organize our lib by both our folder structure itself as well as the names of -functions. For example, `lib.rum.types.gtkType` is found in -`lib/types/gtkType.nix`. In cases where a file is a single function, always be -sure to make sure the name matches the file. - -If a program uses multiple functions of the same kind (e.g. two generators), you -can put them in one file, like is done in `lib/generators/gtk.nix`. - -Additionally, please follow how lib is structured in nixpkgs. For example, the -custom function `attrsNamesHasPrefix` is under `attrsets` to signify that it -operates on an attrset, just like in nixpkgs. - -### Docs - -WIP - -### Tests - -Please refer to the [testing documentation](./TESTING.md) for more information -on how tests work. - -## Reviewing a PR - -Even if you do not have write-access, you can always leave a review on someone -else's PR. Again, GitHub has great [documentation on reviewing PRs]. This is -great practice for learning the guidelines as well as learning exceptions to the -rules. For some guidelines on review practices, see [REVIEWING.md]. diff --git a/docs/footer.html b/docs/footer.html new file mode 100644 index 00000000..a3916d0f --- /dev/null +++ b/docs/footer.html @@ -0,0 +1,12 @@ +
+ Built with ndg from snugnug/hjem-rum +
+
+ Protected under CC-BY-NC-SA 4.0 in accordance with our LICENSE +
+
+ For more information on the SNUG, see our repo +
diff --git a/docs/manual/LICENSE b/docs/manual/LICENSE new file mode 100644 index 00000000..cbe5ad16 --- /dev/null +++ b/docs/manual/LICENSE @@ -0,0 +1,437 @@ +Attribution-NonCommercial-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International +Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-NonCommercial-ShareAlike 4.0 International Public License +("Public License"). To the extent this Public License may be +interpreted as a contract, You are granted the Licensed Rights in +consideration of Your acceptance of these terms and conditions, and the +Licensor grants You such rights in consideration of benefits the +Licensor receives from making the Licensed Material available under +these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-NC-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution, NonCommercial, and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. NonCommercial means not primarily intended for or directed towards + commercial advantage or monetary compensation. For purposes of + this Public License, the exchange of the Licensed Material for + other material subject to Copyright and Similar Rights by digital + file-sharing or similar means is NonCommercial provided there is + no payment of monetary compensation in connection with the + exchange. + + l. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + m. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + n. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part, for NonCommercial purposes only; and + + b. produce, reproduce, and Share Adapted Material for + NonCommercial purposes only. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties, including when + the Licensed Material is used other than for NonCommercial + purposes. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-NC-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database for NonCommercial purposes + only; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + including for purposes of Section 3(b); and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/docs/manual/contributing/docs.md b/docs/manual/contributing/docs.md new file mode 100644 index 00000000..a5acb0a1 --- /dev/null +++ b/docs/manual/contributing/docs.md @@ -0,0 +1,85 @@ +# Contributing: Extending the Documentation {#contributing-extending-the-documentation} + +[ndg]: https://github.com/feel-co/ndg + +If you would like to contribute to our documentation, we ask a few things of +you: + +1. Please aim to write in a formal tone. +2. Use proper grammar and check for misspellings or typos. +3. Try to be concise, but also explain things in full. + +In general, the requirements are very loose, but maintainers may have more +specific asks of you depending on the case. Writing can be very personal and +very fluid, so there are less rigid expectations here, but that does not mean +standards are lower. + +## Nixpkgs Markdown {#ch-nixpkgs-markdown} + +[ndg] supports extended markdown syntax in accordance with Nixpkgs' flavor. + +### Roles {#sec-roles} + +If you are including an option or function labeled like: + +```md +Make sure to use `lib.options.mkEnableOption`, like is done in +`rum.programs.fish.enable`. +``` + +Then you will have to include {file} before it, or {option} if it is an option:[^1] + +```md +Make sure to use {file}`lib.options.mkEnableOption`, like is done in +{option}`rum.programs.fish.enable`. +``` + +[^1]: It is admittedly a bit confusing why we could use {file} for `lib`, but + the best way to think of it is that {file}`lib.modules.mkIf` literally + corresponds to the file {file}`lib/modules.nix` in Nixpkgs, which contains + the `mkIf` function. + +If you do not do it like this, the link check on the docs will fail, since our +docs generator will attempt to make hyperlinks out of those function names. + +### Anchors {#sec-anchors} + +Headers should always have an anchor with them to ensure the link checker can +follow header links at time of build. Follow these examples, and you should find +it simple: + +```md +# My new document page {#my-new-document-page} + +## My 1st chapter heading! {#ch-my-1st-chapter-heading} + +### WHAT_DI-887-NI-DO>????? WRONG ? my cool section! {#sec-what-di-887-ni-do-wrong-my-cool-section} +``` + +Words should be separated by `-`, special characters should be removed, numbers +are fine to keep, extra spaces should be removed, everything should be lower +caps, first headings have no prefix, second headings have `ch` prefix, third +headings have `sec` prefix, etc. If you're unsure, just give it your best shot +and a reviewer will make sure it's as it should be. + +## Other Guidelines {#ch-other-guidelines} + +### Masked Links {#sec-masked-links} + +All links should be "masked," meaning with in-line redirects to their links at +the top of the page directly under the first heading: + +```md +# My Document Page {#my-document-page} + +[cool link]: https://rum.aurabora.org + +Here's my page. + +## First Heading {#ch-first-heading} + +Here's my [cool link]! +``` + +We do this so that paragraph clutter is minimized, making it easier for +reviewers to review and writers to edit. This should be done everywhere. diff --git a/docs/manual/contributing/introduction.md b/docs/manual/contributing/introduction.md new file mode 100644 index 00000000..7e277194 --- /dev/null +++ b/docs/manual/contributing/introduction.md @@ -0,0 +1,127 @@ +# Contributing: Introduction {#contributing-introduction} + +[commitizen]: https://github.com/commitizen-tools/commitizen +[article from GeeksforGeeks]: https://www.geeksforgeeks.org/how-to-create-a-new-branch-in-git/ +[creating a PR]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request +[documentation on forking repositories]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo +[documentation on reviewing PRs]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request +[Core Principles]: #ch-core-principles +[**Contributing: Writing Modules**]: ./writing-modules.html +[#43]: https://github.com/snugnug/hjem-rum/pull/43 +[**Contributing: Setting Up Module Tests**]: ./testing.html +[**Contributing: Extending Hjem Rum's Library**]: ./rumlib.html +[**Contributign: Expanding the Documentation**]: ./docs.html +[reviewed]: #ch-reviewing-a-pr +[**Contributing: Review Tips**]: ./reviewing.html + +Hjem Rum (or HJR) is always in need of contributions as a module collection. As +programs are developed, modules will need to be added, changed, removed, etc., +meaning that the development of HJR is, in essence, unending. + +Contributing is also a great way to learn the Nix module system and even +function writing. Don't be afraid to experiment and try learning something new. + +If you are familiar with contributing to open source software, you can safely +skip ahead to [Core Principles]. Otherwise, read the following section to learn +how to fork a repo and open a PR. + +## Getting Started {#ch-getting-started} + +To begin contributing to HJR, you will first need to create a fork off of the +main branch in order to make changes. For info on how to do this, we recommend +GitHub's own [documentation on forking repositories]. + +Once you have your own fork, it is recommend that you create a branch for the +changes or additions you seek to make, to make it easier to set up multiple PRs +from your fork. To do so, you can read this [article from GeeksforGeeks] that +will also explain branches for you. Don't worry too much about the technical +details, the most important thing is to make and switch to a branch from HEAD. + +### Commit Format {#sec-commit-format} + +> [!TIP] +> Our dev shell allows for interactive commits, through the means of +> [commitizen]. If this is preferred, you can run `cz commit` to be prompted to +> build your commit. + +For consistency, we do enforce a strict (but simple) commit style, that will be +linted against. The format is as follows (sections between `[]` are optional): + +```console +[/]: + +[] +``` + +- \: the main scope of your commit. If making a change to a + program, this would be `programs`). For changes unrelated to the modules API, + we tend to use semantic scopes such as `meta` for CI/repo related changes. + +- \[\]: An optional, more specific scope for your module. If + making changes to a specific program, this would be `programs/foot`. + +- \: A free form commit message. Needs to be imperative and without + punctuation (e.g. `do stuff` instead of `did stuff.`). + +- \[\]: A free form commit body. Having one is encouraged when your + changes are difficult to explain, unless you're writing in-depth code comments + (it is still preferred however). + +You can now make your changes in your editor of choice. After committing your +changes, you can run: + +```shell +git push origin +``` + +and then open up a PR, or "Pull Request," in the upstream HJR repository. Again, +GitHub has good documentation for [creating a PR]. + +After you have setup a PR, it will be [reviewed] by maintainers and changes may +be requested. Make the changes requested and eventually it will likely be +accepted and merged into main. + +## Core Principles {#ch-core-principles} + +In creating HJR, we had a few principles in mind for development: + +1. Minimize the number of options written. +2. Include only the module collection - leave functionality to Hjem. +3. Maintain readability of code, even for new users. + +Please keep these in mind as you read through our general guidelines for +contributing. + +## Writing Modules {#ch-writing-modules} + +Writing modules is a core task of contributing to Hjem Rum, and makes up the +bulk of PRs. Learning to follow our guidelines, standards, and expectations in +writing modules is accordingly crucial. Please see +[**Contributing: Writing Modules**] for more information. + +## Tests {#ch-tests} + +Since [#43], all modules are expected to have tests to ensure their maintained +function through development. Writing tests has a steep learning curve, but +becomes easier over time. Please see [**Contributing: Writing Module Tests**] +for more information. + +## Extending RumLib {#ch-extending-rumlib} + +In writing modules, you may often find yourself in need of a custom function or +two. While writing functions is certainly a more advanced contributing task, it +is absolutely within your range to do. Please see +[**Contributing: Extending Hjem Rum's Library**] for more information. + +## Docs {#ch-docs} + +Please see [**Contributing: Expanding the Documentation**] for information on +this. + +## Reviewing a PR {#ch-reviewing-a-pr} + +Even if you do not have write-access, you can always leave a review on someone +else's PR. GitHub has great [documentation on reviewing PRs]. This is great +practice for learning the guidelines as well as learning exceptions to the +rules. For some guidelines on review practices, see +[**Contributing: Review Tips**]. diff --git a/docs/REVIEWING.md b/docs/manual/contributing/reviewing.md similarity index 92% rename from docs/REVIEWING.md rename to docs/manual/contributing/reviewing.md index 16f71898..cd9811c1 100644 --- a/docs/REVIEWING.md +++ b/docs/manual/contributing/reviewing.md @@ -1,9 +1,9 @@ -# Review tips +# Contributing: Review Tips {#contributing-review-tips} [Code Review Antipatterns]: https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/code-review-antipatterns/ -[nixpkgs]: https://github.com/NixOS/nixpkgs +[Nixpkgs]: https://github.com/NixOS/Nixpkgs [SNUG Discord server]: https://discord.gg/6rMPtKDKzt -[multi-trip reviews]: #2-single-trip-reviews +[multi-trip reviews]: #ch-2-single-trip-reviews An often overlooked part of contributing to an open source project is proper review practices. It's very easy to alienate contributors with bad code review. @@ -18,7 +18,7 @@ tips serve as a reference, not a rule of law. Much of this guide is inspired by [Code Review Antipatterns] by Simon Tatham. If you're interested, give it a look! -## 1. Be nice +## 1. Be nice {#ch-1-be-nice} Starting off with an easy one! However, there's actually something meaningful to be said here. As a reviewer, it's easy to get frustrated with constantly giving @@ -34,7 +34,7 @@ This might sound silly at first. But when it feels like a reviewer is _on your side_, it makes a huge difference. If this tone feels a little foreign, pretend you're writing an email, and that should give you a good barometer. -## 2. Single-trip reviews +## 2. Single-trip reviews {#ch-2-single-trip-reviews} As a contributor, it can be frustrating to finish accommodating all the review comments, only to immediately be given a bunch of other suggestions, which @@ -59,9 +59,9 @@ something will require a lot of changes to be mergeable, be up-front about it―even if you feel a little guilty. Better to rip the bandaid off now, than to leave it on for a few review sessions. -## 3. United front +## 3. United front {#ch-3-united-front} -Anyone who's contributed to [nixpkgs] knows the cycle―you've accommodated one +Anyone who's contributed to [Nixpkgs] knows the cycle―you've accommodated one reviewer's comments, only for a different reviewer to come in with MORE things to change. Or, even worse―maybe reviewer 2 disagrees with reviewer 1―and now they're fighting on your PR. @@ -70,7 +70,7 @@ When possible, try to coordinate review feedback. The [SNUG Discord server] is a great place for working together to ensure feedback is clear and consistent between reviewers. -## 4. Bikeshedding +## 4. Bikeshedding {#ch-4-bikeshedding} Have you ever made a PR, only for every single line to be criticized for not being done exactly how the reviewer wants? It feels like your code is being held @@ -108,7 +108,7 @@ Maybe, if it's a stylistic change, say: > Stylistic nitpick, but could you maybe change this to ____? Not blocking. -# Extending this document +## Extending this document {#ch-extending-this-document} If you find yourself experiencing something as a contributor that makes you less motivated to contribute―whether it's for Hjem Rum or some other project―feel diff --git a/docs/manual/contributing/rumlib.md b/docs/manual/contributing/rumlib.md new file mode 100644 index 00000000..91dc4d8b --- /dev/null +++ b/docs/manual/contributing/rumlib.md @@ -0,0 +1,27 @@ +# Contributing: Extending Hjem Rum's Library {#contributing-extending-hjem-rum-library} + +Rather than having functions scattered throughout the module collection, we +would rather keep our directories organized and purposeful. Therefore, all +custom functions should go into our extended lib, found at `modules/lib/`. + +The most common functions that might be created are a `generator` and `type` +pair. The former should be prefixed with "to" to maintain style and describe +their function: conversion _to_ other formats. For example, `toNcmpcppSettings` +is the function that converts to the format required for ncmpcpp settings. + +Likewise, types should be suffixed with "Type" to maintain style and describe +their function. For example, `hyprType` describes the type used in `settings` +converted to Hyprlang. + +When it comes to directory structure, you should be able to infer how we +organize our lib by both our folder structure itself as well as the names of +functions. For example, {option}`rumLib.types.gtkType` is found in +`lib/types/gtkType.nix`. In cases where a file is a single function, always be +sure to make sure the name matches the file. + +If a program uses multiple functions of the same kind (e.g. two generators), you +can put them in one file, like is done in `lib/generators/gtk.nix`. + +Additionally, please follow how lib is structured in Nixpkgs. For example, the +custom function `attrsNamesHasPrefix` is under `attrsets` to signify that it +operates on an attribute set, just like in Nixpkgs. diff --git a/docs/TESTING.md b/docs/manual/contributing/testing.md similarity index 74% rename from docs/TESTING.md rename to docs/manual/contributing/testing.md index 9c7ee215..b58b4b44 100644 --- a/docs/TESTING.md +++ b/docs/manual/contributing/testing.md @@ -1,23 +1,24 @@ -# Testing setup for modules +# Contributing: Setting Up Module Tests {#contributing-setting-up-module-tests} -[ncmpcpp test module]: ../modules/tests/programs/ncmpcpp/ncmpcpp.nix +[nushell test module]: https://github.com/snugnug/hjem-rum/blob/main/modules/tests/programs/nushell.nix [nix.dev provides a useful guide]: https://nix.dev/tutorials/nixos/integration-testing-using-virtual-machines.html [NixOS Manual]: https://nixos.org/manual/nixos/stable/index.html#sec-calling-nixos-tests [internal NixOS lib]: https://github.com/NixOS/nixpkgs/tree/master/nixos/lib/testing Hjem Rum's testing system is designed with simplicity in mind, so we shy away from other testing frameworks and stick with `runTest`, from the -[internal NixOS lib] located in the nixpkgs monorepo. There are no non-standard +[internal NixOS lib] located in the Nixpkgs monorepo. There are no non-standard abstractions in regards to writing the tests, so they should be written just like any other test that uses the NixOS Test Driver. -## Creating tests +## Creating Tests {#ch-creating-tests} -Every file is automatically imported with `lib.filesystem.listFilesRecursive`, -given that there is a check output that imports the directory (more on that -later), so your only worry should be creating the tests in their relevant -directories. If you're writing a test for btop, for instance, you should create -a module as `/modules/tests/programs/btop.nix`. +Every file is automatically imported with +{file}`lib.filesystem.listFilesRecursive`, given that there is a check output +that imports the directory (more on that later), so your only worry should be +creating the tests in their relevant directories. If you're writing a test for +btop, for instance, you should create a module as +`modules/tests/programs/btop.nix`. If you're certain your test category doesn't get covered by any of the existing directories, you can create a new one together with a check that imports files @@ -28,7 +29,7 @@ checks = hjem-rum-services = import ./modules/tests (mkCheckArgs ./modules/tests # Just // (import ./modules/tests and pass mkCheckArgs with your brand-new directory to it. ``` -### Naming +### Naming {#sec-naming} To reduce CI run time, we only run checks for which the module or test file has changed. For this association to work, the following naming scheme has to be @@ -46,11 +47,11 @@ start with the aformentioned pattern, such as `programs-foot-test-plugins`. > [!IMPORTANT] > If you do not follow this rule, your tests will not be run during CI. -## Writing tests +## Writing Tests {#ch-writing-tests} Tests for Hjem Rum are written just like any other test, so it might be worth to take a read at how NixOS tests work. [nix.dev provides a useful guide], as does -the [NixOS Manual][^1], both detailing how to use the framework. +the [NixOS Manual],[^1] both detailing how to use the framework. Our test system has some pre-defined things aiming at avoid boilerplate code: @@ -61,8 +62,8 @@ Our test system has some pre-defined things aiming at avoid boilerplate code: `self`, `lib` and `pkgs` are also passed to every test module, so you're free to use them as you will. -The [ncmpcpp test module] was written to serve as an example for future tests, -and provides comments for each step of the `testScript`. Care should be taken to +The [nushell test module] can serve as a strong example of a test module, and +provides comments for each step of the `testScript`. Care should be taken to wait for the proper systemd targets to be reached, change users to run commands, and avoid other possible footguns. The approach this module uses to test its configuration is to have a file for each configuration alongside it, which then @@ -75,7 +76,7 @@ You can also debug your tests through a Python REPL by running: nix run .#checks..vm-test-run--[-suffix].driver -- --interactive ``` -[^1]: Although both guides refer to `lib.tests.runNixOSTest` instead of +[^1]: Although both guides refer to {file}`lib.tests.runNixOSTest` instead of `runTest`, the former is just a wrapper around the latter, abstracting certain concepts, so the code ran by them should be interchangeable between one another. diff --git a/docs/manual/contributing/writing-modules.md b/docs/manual/contributing/writing-modules.md new file mode 100644 index 00000000..be584eb7 --- /dev/null +++ b/docs/manual/contributing/writing-modules.md @@ -0,0 +1,322 @@ +# Contributing: Writing Modules {#contributing-writing-modules} + +[Noogle's page on it]: https://noogle.dev/f/lib/options/mkPackageOption + +Writing modules is a core task of contributing to Hjem Rum, and makes up the +bulk of PRs. Learning to follow our guidelines, standards, and expectations in +writing modules is accordingly crucial. Please read the following to be made +aware of these. + +## Aliases {#ch-aliases} + +At the top of any module, there should always be a `let ... in` set. Within +this, functions should have their location aliased, cfg should be aliased, and +any generators should have an alias as well. Here's an example for a module that +makes use of the TOML generator used in Nixpkgs: + +```nix +{ + config, + lib, + pkgs, + ... +}: let + # in case you are unfamiliar, 'inherit func;' is the same as 'func = func;', and + # 'inherit (cfg) func;' is the same as 'func = cfg.func;' + inherit (lib.modules) mkIf; + inherit (lib.options) mkOption mkEnableOption mkPackageOption; + + toml = pkgs.formats.toml {}; + + cfg = config.rum.programs.alacritty; +in { + options.rum.programs.alacritty = { +``` + +Notice that each function has its location aliased with an inherit to its target +location. Ideally, this location should be where one could find it in the source +code. For example, rather than using {file}`lib.mkIf`, we use +{file}`lib.modules.mkIf`, because mkIf is declared at `lib/modules.nix` within +the Nixpkgs repo. + +Also notice that in this case, `pkgs.formats.toml {}` includes both `generate` +and `type`, so the alias name is just `toml`. + +Always be sure to include `cfg` that links to the point where options are +configured by the user. + +## Writing Options {#ch-writing-options} + +Writing new options is the core of any new module. It is also the easiest place +to blunder. As stated above, a core principle of HJR is to minimize the number +of options as much as possible. As such, we have created a general template that +should help inform you of what options are needed and what are not: + +- `enable`: Used to toggle install and configuration of package(s). +- `package`: Used to customize and override the package installed. + - As needed, `packages`: List of packages used in a module. +- `settings`: Primary configuration option, takes Nix code and converts to + target lang. + - As needed, one extra option for each extra file, such as `theme` for + theme.toml. +- As needed, `extraConfig`: Extra lines of strings passed directly to config + file for certain programs. + +For the most part, this should be sufficient. + +### Package Overrides {#sec-package-overrides} + +Overrides of packages should be simply offered through a direct override in +`package`. For example, ncmpcpp's package has a `withVisualizer ? false` +argument. Rather than creating an extra option for this, the contributor should +note this with `extraDescription`, and give an example of it like so: + +```nix +options.rum.programs.ncmpcpp = { + enable = mkEnableOption "ncmpcpp, a mpd-based music player."; + + package = mkPackageOption pkgs "ncmpcpp" { + nullable = true; # Always enable `nullable` in `mkPackageOption`. Usually, this would be inline. + extraDescription = '' + You can override the package to customize certain settings that are baked + into the package. + ''; + # Note that mkPackageOption's example automatically uses literalExpression + example = '' + pkgs.ncmpcpp.override { + # useful overrides in the package + outputsSupport = true; # outputs screen + visualizerSupport = false; # visualizer screen + clockSupport = true; # clock screen + taglibSupport = true; # tag editor + }; + ''; + }; +``` + +and the user could simply pass: + +```nix +config.hjem.users..rum.programs.ncmpcpp = { + enable = true; + package = (pkgs.ncmpcpp.override { + withVisualizer = true; + }); +}; +``` + +### Nullable Package Options {#sec-nullable-package-options} + +When using `mkPackageOption`, you should always be sure to enable `nullable`, so +that the user can choose not to have Hjem Rum install the package into the +user's environment. + +```nix +options.rum.programs.alacritty = { + enable = mkEnableOption "Alacritty"; + + package = mkPackageOption pkgs "alacritty" {nullable = true;}; +}; +``` + +`mkPackageOption` is a function with three required arguments: the source of the +package (usually `pkgs`), the name of the package, and an attribute set for +configuration. The latter has several options, such as `extraDescription`, +`example`, and, in this case `nullable`. For a complete list of options for this +function, see [Noogle's page on it]. + +Because the user can set the package to null, however, we must check for this +before adding the package to the user's environment, as adding `null` would +result in an error. Thankfully, this is relatively simple: + +```nix +config = mkIf cfg.enable { + packages = mkIf (cfg.package != null) [cfg.package]; +}; +``` + +This simply checks if the package is null before adding it to the list. + +### Type {#sec-type} + +The `type` of `settings` and other conversion options should preferably be a +`type` option exposed by the generator (for example, TOML has +`pkgs.formats.toml {}.type` and `pkgs.formats.toml {}.generate`), or, if using a +custom generator, a `type` should be created in `lib/types/` (for example, +`hyprType`). Otherwise, a simple `attrsOf anything` would suffice. + +### Submodules / Nested Configuration {#sec-submodules-nested-configuration} + +As a rule of thumb, submodules should not be employed. Instead, there should +only be one option per file. For some files, such as spotify-player's +{file}`keymap.toml`, you may be tempted to create multiple options for `actions` +and `keymaps`, as Home Manager does. Please avoid this. In this case, we can +have a simple `keymap` option that the user can then include a list of keymaps +and/or a list of actions that get propagated accordingly: + +```nix + keymap = mkOption { + inherit (toml) type; # We can use a streamlined inherit to say type = toml.type + default = {}; + example = { + keymaps = [ + { + command = "NextTrack"; + key_sequence = "g n"; + } + ]; + actions = [ + { + action = "GoToArtist"; + key_sequence = "g A"; + } + ]; + }; + description = '' + Sets of keymaps and actions converted into TOML and written to + {file}`$HOME/.config/spotify-player/keymap.toml`. + See example for how to format declarations. + + Please reference https://github.com/aome510/spotify-player/blob/master/docs/config.md#keymaps + for more information. + ''; + }; +``` + +Also note that the option description includes a link to upstream info on +settings options. + +### Dependence on `config` {#sec-dependence-on-config} + +If an option is dependent on `config`, (e.g. +`default = config.myOption.enable;`) you must _also_ set `defaultText` alongside +`default`. Example: + +```nix +integrations = { + # We basically override the `default` and `defaultText` attrs in the mkEnableOption function + fish.enable = mkEnableOption "starship integration with fish" // { + default = config.programs.fish.enable; + defaultText = "config.programs.fish.enable"; + }; +}; +``` + +It is essentially just a string that shows the user what the option is set to by +default. This can also be used in `mkOption`, but it is more common to use it in +`mkEnableOption`. + +If you do not set this, the docs builder will break due to not knowing how to +resolve the reference to `config`. + +## Conditionals in Modules {#ch-conditionals-in-modules} + +Always use a `mkIf` before the `config` section. Example: + +```nix +config = mkIf cfg.enable { + # Module code +}; +``` + +As a general guideline, **do not write empty strings to files**. Not only is +this poorly optimized, but it will cause issues if a user happens to be manually +using the Hjem tooling alongside HJR. Here are some examples of how you might +avoid this: + +```nix +config = mkIf cfg.enable { + packages = [cfg.package]; + files.".config/alacritty/alacritty.toml".source = mkIf (cfg.settings != {}) ( + toml.generate "alacritty.toml" cfg.settings # The indentation makes it more readable + ); +}; +``` + +Here all that is needed is a simple `mkIf` with a condition of the `settings` +option not being left empty. In a case where you write to multiple files, you +can use `optionalAttrs`, like so: + +```nix +files = ( + optionalAttrs (cfg.settings != {}) { + ".gtkrc-2.0".text = toGtk2Text {inherit (cfg) settings;}; + ".config/gtk-3.0/settings.ini".text = toGtkINI {Settings = cfg.settings;}; + ".config/gtk-4.0/settings.ini".text = toGtkINI {Settings = cfg.settings;}; + } + // optionalAttrs (cfg.css.gtk3 != "") { + ".config/gtk-3.0/gtk.css".text = cfg.css.gtk3; + } + // optionalAttrs (cfg.css.gtk4 != "") { + ".config/gtk-4.0/gtk.css".text = cfg.css.gtk4; + } +); +``` + +This essentially takes the attribute set of `files` and _conditionally_ adds +attributes defining more files to be written to depending on _if_ the +corresponding option has been set. This is optimal because the first three files +written to share an option due to how GTK configuration works. + +One last case is in the Hyprland module, where several checks and several +options are needed to compile into one file. Here is how it is done: + +```nix +files = let + check = { + plugins = cfg.plugins != []; + settings = cfg.settings != {}; + variables = { + noUWSM = config.environment.sessionVariables != {} && !osConfig.programs.hyprland.withUWSM; + withUWSM = config.environment.sessionVariables != {} && osConfig.programs.hyprland.withUWSM; + }; + extraConfig = cfg.extraConfig != ""; + }; +in { + ".config/hypr/hyprland.conf".text = mkIf (check.plugins || check.settings || check.variables.noUWSM || check.extraConfig) ( + optionalString check.plugins (pluginsToHyprconf cfg.plugins cfg.importantPrefixes) + + optionalString check.settings (toHyprconf { + attrs = cfg.settings; + inherit (cfg) importantPrefixes; + }) + + optionalString check.variables.noUWSM (toHyprconf { + attrs.env = + # https://wiki.hyprland.org/Configuring/Environment-variables/#xdg-specifications + [ + "XDG_CURRENT_DESKTOP,Hyprland" + "XDG_SESSION_TYPE,wayland" + "XDG_SESSION_DESKTOP,Hyprland" + ] + ++ mapAttrsToList (key: value: "${key},${value}") config.environment.sessionVariables; + }) + + optionalString check.extraConfig cfg.extraConfig + ); + + /* + uwsm environment variables are advised to be separated + (see https://wiki.hyprland.org/Configuring/Environment-variables/) + */ + ".config/uwsm/env".text = + mkIf check.variables.withUWSM + (toEnvExport config.environment.sessionVariables); + + ".config/uwsm/env-hyprland".text = let + /* + this is needed as we're using a predicate so we don't create an empty file + (improvements are welcome) + */ + filteredVars = + filterKeysPrefixes ["HYPRLAND_" "AQ_"] config.environment.sessionVariables; + in + mkIf (check.variables.withUWSM && filteredVars != {}) + (toEnvExport filteredVars); +}; +``` + +An additional attribute set of boolean aliases is set within a `let ... in` set +to highlight the different checks done and to add quick ways to reference each +check without excess and redundant code. + +First, the file is only written if any of the options to write to the file are +set. `optionalString` is then used to compile each option's results in an +optimized and clean way. diff --git a/docs/manual/index.md b/docs/manual/index.md new file mode 100644 index 00000000..a862e92a --- /dev/null +++ b/docs/manual/index.md @@ -0,0 +1,21 @@ +# Hjem Rum {#index} + +[**Hjem Rum**]: ./index.html +[**Options**]: ./options.html +[**Search**]: ./search.html +[**Usage: Installing Hjem Rum**]: ./usage/installation.html +[**Contributing: Introduction**]: ./contributing/introduction.html + +Welcome to Hjem Rum's Official Documentation. + +In the top right, you can see the option search menu. In the top left, you can +click [**Hjem Rum**] for this page, [**Options**] for the options page, and +[**Search**] for the full option search page. + +If you are looking to install Hjem Rum, please start with +[**Usage: Installing Hjem Rum**], and see the other documents prefixed with +**Usage:** in the sidebar. + +If you are looking to contribute to Hjem Rum, please start with +[**Contributing: Introduction**] and see the other documents prefixed with +**Contributing:** in the sidebar. diff --git a/docs/manual/usage/installation.md b/docs/manual/usage/installation.md new file mode 100644 index 00000000..bdcb6ad3 --- /dev/null +++ b/docs/manual/usage/installation.md @@ -0,0 +1,277 @@ +# Usage: Installing Hjem Rum {#usage-installing-hjem-rum} + +[**Options**]: ../options.html +[**Quirks, Tips, and Tricks**]: ./quirks.html + +Welcome to Hjem Rum. Installing and configuring Hjem Rum is as easy as any other +module. + +## Importing the Hjem Rum Flake {#ch-importing-the-hjem-rum-flake} + +To begin using Hjem Rum, simply add and import Hjem and Hjem Rum into your +flake: + +```nix +# flake.nix +inputs = { + nixpkgs.url = "github:NixOS/nixpkgs?ref=nixos-unstable"; + # To minimize redundancies, we suggest you set your flakes to follow your inputs. + hjem = { + url = "github:feel-co/hjem"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + hjem-rum = { + url = "github:snugnug/hjem-rum"; + inputs = { + nixpkgs.follows = "nixpkgs"; + hjem.follows = "hjem"; + }; + }; +}; + +# One example of importing the module into your system configuration +outputs = { + self, + nixpkgs, + ... +} @ inputs: { + nixosConfigurations = { + default = nixpkgs.lib.nixosSystem { + specialArgs = {inherit inputs;}; + modules = [ + inputs.hjem.nixosModules.default # Import the hjem module + ./configuration.nix + ]; + }; + }; +} +``` + +## Using Hjem Rum Modules {#ch-using-hjem-rum-modules} + +You can declare Hjem Rum modules either in a NixOS module, imported into all +your hosts, or as a special Hjem module, imported directly into Hjem. If you do +not know which to choose, we recommend configuring Hjem Rum in NixOS modules. + +> [!INFO] +> For the purposes of this example, we will be pretending your username is +> `alice`. + +### Configuring in a NixOS Module {#sec-configuring-in-a-nixos-module} + +To configure Hjem Rum in a NixOS Module, set the according settings, import Hjem +Rum's flake output, and configure away. + +```nix +# configuration.nix +{ + pkgs, + inputs, + ... +}: { + hjem = { + # Import the module collection + extraModules = [inputs.hjem-rum.hjemModules.default]; + + # We recommend using the experimental linker + linker = inputs.hjem.packages."x86_64-linux".smfh; # Use your host's system + + # Configuring your user(s) + users.alice = { + enable = true; + directory = "/home/alice"; + user = "alice"; + rum.programs.alacritty = { + enable = true; + package = pkgs.alacritty; # Default + settings = { + window = { + dimensions = { + lines = 28; + columns = 101; + }; + padding = { + x = 6; + y = 3; + }; + }; + }; + }; + }; + }; +} +``` + +This setup is ideal for a single-user configuration, as you can easily integrate +your home configuration right in your system. It minimizes friction and creates +a single-setup configuration. You can, of course, modularize your configuration +into files, like you should do for NixOS: + +```nix +# configuration.nix +{ + imports = [./hjem]; +} +``` + +```nix +# hjem/default.nix +{ + config, + inputs, + ... +}: { + imports = [ + ./alacritty.nix + ]; + config.hjem = { + # Import the module collection + extraModules = [inputs.hjem-rum.hjemModules.default]; + + # We recommend using the experimental linker + linker = inputs.hjem.packages."x86_64-linux".smfh; # Use your host's system + + # Configuring your user(s) + users.alice = { + enable = true; + directory = "/home/alice"; + user = "alice"; + }; + }; +} +``` + +```nix +# hjem/alacritty.nix +{pkgs,...}: { + hjem.users.alice.rum.programs.alacritty = { + enable = true; + package = pkgs.alacritty; # Default + settings = { + window = { + dimensions = { + lines = 28; + columns = 101; + }; + padding = { + x = 6; + y = 3; + }; + }; + }; + }; +} +``` + +Using this setup, a single-user configuration can be well implemented into your +existing NixOS configuration. For example, you could configure the necessary +system-wide configurations for your desktop environment and manage its dotfiles +in the same file or directory. + +### Configuring in a Hjem Module {#sec-configuring-in-a-hjem-module} + +Alternatively, if you would rather separate your Hjem modules from your NixOS +modules, you can simply import Hjem Rum's modules and Nix files written as Hjem +modules straight into your Hjem user. + +```nix +# configuration.nix +{inputs, ...}: { + hjem = { + # Import the module collection + extraModules = [inputs.hjem-rum.hjemModules.default]; + + # We recommend using the experimental linker + linker = inputs.hjem.packages."x86_64-linux".smfh; # Use your host's system + + # Configuring your user(s) + users.alice = { + enable = true; + directory = "/home/alice"; + user = "alice"; + imports = [./hjem/alice]; + }; + }; +} +``` + +```nix +# hjem/alice/default.nix +{ + imports = [./alacritty.nix]; +} +``` + +```nix +# hjem/alice/alacritty.nix +{pkgs, ...}: { + rum.programs.alacritty = { + enable = true; + package = pkgs.alacritty; # Default + settings = { + window = { + dimensions = { + lines = 28; + columns = 101; + }; + padding = { + x = 6; + y = 3; + }; + }; + }; + }; +} +``` + +In this example, Alacritty would only be enabled and configured in the user the +module is imported into. Using this setup, you could also import Hjem Rum +exclusively into the user, rather than into {option}`hjem.extraModules`. + +```nix +# configuration.nix +{inputs, ...}: { + hjem = { + # Don't import the flake into all users + extraModules = []; + + # Instead, import it into a single user + users.alice = { + imports = [ + inputs.hjem-rum.hjemModules.default + ./hjem/alice + ]; + }; + }; +} +``` + +Keep in mind, if you wish to access any specialArgs, you will need to declare +them in {option}`hjem.specialArgs`: + +```nix +# configuration.nix +{inputs, ...}: { + hjem = { + specialArgs = {inherit inputs;}; # inputs = inputs + users.alice.imports = [./hjem/alice]; + }; +} +``` + +```nix +# hjem/alice/default.nix +{inputs, ...}: { + imports = [inputs.hjem-rum.hjemModules.default]; +} +``` + +In this example, this allows us to import the Hjem Rum collection inside of a +user-specific Hjem module. + +## Beyond Installation {#ch-beyond-installation} + +Please see [**Options**] for a thorough list of options you can set. + +Additionally, please see [**Usage: Quirks, Tips, and Tricks**] for important +information regarding your usage of Hjem Rum. diff --git a/docs/manual/usage/quirks.md b/docs/manual/usage/quirks.md new file mode 100644 index 00000000..36858658 --- /dev/null +++ b/docs/manual/usage/quirks.md @@ -0,0 +1,41 @@ +# Usage: Quirks, Tips, & Tricks {#usage-quirks-tips-tricks} + +[#17]: https://github.com/snugnug/hjem-rum/issues/17 + +As you are getting familiar with Hjem Rum, you may find some strange quirks that +you are unfamiliar with. This is especially so as unlike Home Manager, the +underlying toolset implementation is a wholly separate project, with Hjem Rum +serving only as a module collection on top of Hjem. + +To help alleviate this, here are some of those quirks that you may find, as well +as some tips to help you on your journey with Hjem Rum. + +## Environmental Variables {#ch-environmental-variables} + +Hjem provides the option {option}`environment.sessionVariables` allowing the +user to set environmental variables to be sourced. However, Hjem does not have +the capability to actually source them. This can be done manually by the user, +but Hjem Rum integrates it directly into our modules. For example, if you use +Hjem Rum to install and configure zsh, your sessionVariables set in Hjem will be +made available. + +Currently, some of our modules may add environmental variables (such as our GTK +module), but cannot load them without the use of another module. Currently, +modules that load environmental variables include: + +- `rum.programs.fish.enable` +- `rum.programs.nushell.enable` +- `rum.programs.zsh.enable` +- `rum.desktops.hyprland.enable` + +If you are either using something like our GTK module, or are manually adding +variables to {option}`environment.sessionVariables`, but are neither loading +those variables manually, or using one of the above modules, those variables +will not be loaded. This will likely cause you problems. For example, GTK +applications may not respect your theme, as many rely on the environmental +variable to actually use the theme you declare. + +Please see [#17] for status on providing support for shells and compositors. If +your shell or compositor is on listed there, please leave a comment and it will +be added. You are encouraged to open a PR to help support your shell or +compositor if possible. diff --git a/docs/package.nix b/docs/package.nix index 8bc3c074..99f20083 100644 --- a/docs/package.nix +++ b/docs/package.nix @@ -73,7 +73,7 @@ }; configJSON = (pkgs.nixosOptionsDoc { - variablelistId = "hjr-options"; + variablelistId = "hjem-rum-options"; warningsAreErrors = true; options = (evaluatedModules.options.hjem.users.type.getSubOptions []).rum; @@ -110,17 +110,25 @@ .optionsJSON; hjemRumDocs = - pkgs.runCommandLocal "hjr-docs" {nativeBuildInputs = [ndg];} + pkgs.runCommandLocal "hjem-rum-docs" {nativeBuildInputs = [ndg];} '' mkdir -p $out + footer=$(cat ${./footer.html}) + ndg --verbose html \ - --jobs $NIX_BUILD_CORES --title "Hjem Rum" \ + --title "Hjem Rum" \ + --jobs $NIX_BUILD_CORES \ --module-options ${configJSON}/share/doc/nixos/options.json \ --manpage-urls ${./manpage-urls.json} \ - --options-depth 2 \ + --options-depth 3 \ --generate-search true \ + --highlight-code true \ + --footer "$footer" \ + --input-dir ${./manual} \ --output-dir "$out" + + cat ${./CNAME} > "$out/CNAME" # use the CNAME ''; in hjemRumDocs diff --git a/flake.lock b/flake.lock index 32900c3e..1d3029a7 100644 --- a/flake.lock +++ b/flake.lock @@ -72,6 +72,7 @@ }, "original": { "owner": "feel-co", + "ref": "colmark", "repo": "ndg", "type": "github" } diff --git a/flake.nix b/flake.nix index 47af7be0..380e5d42 100644 --- a/flake.nix +++ b/flake.nix @@ -12,7 +12,7 @@ inputs.nixpkgs.follows = "nixpkgs"; }; ndg = { - url = "github:feel-co/ndg"; + url = "github:feel-co/ndg?ref=colmark"; inputs.nixpkgs.follows = "nixpkgs"; }; }; @@ -42,8 +42,11 @@ programs.deno.enable = true; programs.shfmt.enable = true; - settings = { - deno.includes = ["*.md"]; + settings.formatter = { + deno = { + # Exclude the footer because we specifically need ' over " + excludes = ["docs/footer.html"]; + }; }; }); in { @@ -54,11 +57,18 @@ }; default = self.hjemModules.hjem-rum; }; - packages = forAllSystems (pkgs: { + packages = forAllSystems (pkgs: let docs = pkgs.callPackage ./docs/package.nix { inherit (ndg.packages.${pkgs.system}) ndg; inherit rumLib inputs; }; + in { + inherit docs; + docsLinkCheck = pkgs.testers.lycheeLinkCheck { + site = docs; + remap."rum.snugnug.org" = docs; + extraConfig.exclude = []; + }; }); lib = rumLib; diff --git a/modules/collection/desktops/hyprland.nix b/modules/collection/desktops/hyprland.nix index 8e3360e2..7a4b72b1 100644 --- a/modules/collection/desktops/hyprland.nix +++ b/modules/collection/desktops/hyprland.nix @@ -63,7 +63,7 @@ in { type = lines; default = ""; description = '' - Extra configuration that will be appended verbatim at the end of your `hyprland.conf`. + Extra configuration that will be appended verbatim at the end of {file}`~/.config/hypr/hyprland.conf`. ''; }; }; diff --git a/modules/collection/programs/fish.nix b/modules/collection/programs/fish.nix index d2bfd1f5..b9b8ae8c 100644 --- a/modules/collection/programs/fish.nix +++ b/modules/collection/programs/fish.nix @@ -126,7 +126,7 @@ in { - /share/fish/vendor_completions.d - /share/fish/vendor_functions.d - This will be the case with plugins present in `pkgs.fishPlugins`. + This will be the case with plugins present in {file}`pkgs.fishPlugins`. For the remaining cases, a file will be created at `~/.config/fish/conf.d/rum-plugin-.fish`. It will attempt to handle or source a variety of expected files from the derivation. Those files are: