docs: add CONTRIBUTING.md and related instructions

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to nix-topology
+
+This document is mainly intended for people who want to contribute to nix-topology.
+As a short reminder, this is generally what you would need to do:
+
+1. Fork and clone the repository
+2. Either stay on the `main` branch, or create a new branch for your feature `[feat|fix|...]/<name>`.
+   If you are working on multiple PRs at the same time, you should create new branches.
+3. Run `nix develop`. You will be put into a shell with a pre-commit-hook that automatically
+   checks and lints your changes before you push.
+4. Read the chapter below and implement your changes
+5. Once finished, create a commit, push your changes and submit a PR.
+
+## Requirements for submitted changes
+
+If you want to submit a change, please make sure you have checked the following things:
+
+- All checks must pass. You can run them with `nix flake check`, which will also check formatting.
+- The documentation must build successfully, you can run it with `nix build .#docs`.
+  The examples also serve as our tests and are automatically included in the docs.
+- This repository follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) style.
+  So each commit in your PR should contain only one logical change and the commit message
+  should reflect that accordingly.
+
+  Example: If your PR adds two service extractors, you should also have two commits:
+  - `feat(extractors/services): Add support for vaultwarden`
+  - `feat(extractors/services): Add support for forgejo`
+
+  Changes to extractors should be scoped like `feat(extractors/<extractor_name>)`,
+  same for `renderers/<renderer_name>` and `options/<option_name>`. If a change
+  doesn't fit any of these scopes, then just don't add a scope.
+- I'm generally happy to accept any extractor, but please make sure they
+  meet the [extractor criteria from the documentation](https://oddlama.github.io/nix-topology/internals/development.html)
+
+Please also read through the [Development](https://oddlama.github.io/nix-topology/internals/development.html) section in the documentation,
+as it contains some general information about the project and also some hints,
+for example on how to add an extractor.

README.md

@@ -181,6 +181,7 @@ Yep, there's still a lot that could be added or improved.
 
 Contributions are whole-heartedly welcome! Please feel free to suggest new features,
 implement extractors, other stuff, or generally help out if you'd like. We'd be happy to have you.
+There's more information in [CONTRIBUTING.md](CONTRIBUTING.md) and the [Development Chapter](./development.html) in the docs.
 
 ## 📜 License
 

docs/src/SUMMARY.md

@@ -14,10 +14,12 @@
   - [Adding Networks](./networks.md)
 - [Topology Options](./topology-options.md)
 
-# Internal architecture
+# Internals
 
-- [Architecture](./architecture/architecture.md)
-- [Extractors](./architecture/extractors.md)
+- [Architecture](./internals/architecture.md)
+- [Extractors](./internals/extractors.md)
+- [Development](./internals/development.md)
 
 # Examples
 
+<!-- Examples must come last, since the examples are appended automatically by the build script! -->

docs/src/architecture/architecture.md → docs/src/internals/architecture.md

@@ -19,7 +19,7 @@ node asssigned to your nixos host, available as `topology.self`.
 
 Each NixOS host automatically extracts information from your NixOS configuration and exposes
 them in a structured format that is defined by the main topology module. For an overview
-over what is available, please refer to the [available options](https://oddlama.github.io/nix-topology/topology-options.html)
+over what is available, please refer to the [available options](../topology-options.html)
 
 ## 🤬 Caveats
 

docs/src/internals/development.md

@@ -0,0 +1,127 @@
+# Development
+
+First of all, here's a very quick overview over the codebase:
+
+- `examples/` each folder in here should contain a `flake.nix` as a user would write it for their configuration.
+   Each such example flake will automatically be evaluated and rendered in the documentation.
+- `icons/` contains all the service, device and interface icons. Placing a new file here will automatically register it.
+- `nixos/` contains anything related to the provided NixOS module. Mostly information extractors.
+- `options/` contains shared options. Shared means that all of these options will be present
+   both in the global topology module and also in each NixOS module under the `topology` option,
+   which will be merged into the global topology. If you need NixOS specific options (like extractors) or topology specific options (like renderers)
+   have a look at `nixos/module.nix` and `topology/default.nix`.
+- `pkgs/` contains our nixpkgs overlay and packages required to render the graphs.
+- `topology/` contains anything related to the global topology module. This is where the NixOS configurations
+   are merged into the global topology and where the renderers are defined.
+
+## Criteria for new extractors and service extractors
+
+I'm generally happy to accept any extractor, but please make sure they meet the following criteria:
+
+- It must provide an `enable` option so it can be disabled. It may be enabled by default, if it is a no-op
+  for systems that don't use the relevant parts. The services extractor for example guards all assignments
+  behind `mkIf config.services.<service_name>.enable` to make sure that it works for systems that don't use a particular service.
+- The default settings of an extractor (or any part of it) should try not to cause clutter in the generated cards.
+  Take for example OpenSSH which is usually enabled on all machines. Showing it by default would cause a lot of unnecessary clutter,
+  so it should be guarded behind an additional option that is disabled by default. Same goes for common local services like smartd, fwupd, ...
+- Extractors should be made for things available in nixpkgs or the broader list of community projects.
+  So I'm happy to accept extractors for projects like (microvm.nix, disko, ...) but if you want to extract
+  information from very niche or personal projects, it might be better to include the extractor in there.
+
+  If you write an extractor for such a third party dependency, make sure that it is either disabled by default,
+  or guarded in a way so that it doesn't affect vanilla systems. Check the microvm extractor for an example which
+  makes sure that the microvm module is acutually used on the target system.
+
+## Adding a new extractor
+
+To add a whole new extractor, all you need to do is to create `nixos/extractors/foo.nix`,
+and add a new option for your extractor:
+
+```nix
+{ config, lib, ... }: let
+  inherit (lib) mkEnableOption mkIf;
+in {
+  options.topology.extractors.foo.enable = mkEnableOption "topology foo extractor" // {default = true;};
+  config = mkIf (config.topology.extractors.foo.enable && /* additional checks if necessary */) {
+    topology = {
+      # Modify topology based on the information you gathered
+    };
+  };
+}
+```
+
+The file will automatically be included by the main NixOS module.
+
+## Adding a service to the services extractor
+
+To add a new service to the services extractor, all you need to do is
+to add the relevant attribute to the body of the extractor. Please keep them sorted alphabetically.
+
+Imagine we want to add support for vaultwarden, we would start by extracting some information,
+while making sure there's a sensible fallback value at all times if the value isn't set.
+Don't depend on any value being set, only observe what the user has actually configured!
+
+```nix
+vaultwarden = let
+  # Extract domain, address and port if they were set
+  domain = config.services.vaultwarden.config.domain or config.services.vaultwarden.config.DOMAIN or null;
+  address = config.services.vaultwarden.config.rocketAddress or config.services.vaultwarden.config.ROCKET_ADDRESS or null;
+  port = config.services.vaultwarden.config.rocketPort or config.services.vaultwarden.config.ROCKET_PORT or null;
+in
+  # Only assign anything if the service is enabled
+  mkIf config.services.vaultwarden.enable {
+    # The service's proper name.
+    name = "Vaultwarden";
+    # An icon from the icon registry. We will add a new icon for the service later.
+    icon = "services.vaultwarden";
+    # One line of information that should be shown below the service name.
+    # Usually this should be the hosted domain name (if it is known), or very very important information.
+    # For vaultwarden, we the domain in the config. If you are unsure for your service, just leave
+    # it out so users can set it manually via topology.self.services.<service>.info = "...";
+    info = mkIf (domain != null) domain;
+    # In details you can add more information specific to the service.
+    # Currently I tried to include a `listen` detail for any service listening on an address/port.
+    # Samba for example shows the configured shares and nginx the configured reverse proxies.
+    # If you are unsure what to do here, just leave it out.
+    details.listen = mkIf (address != null && port != null) {text = "${address}:${toString port}";};
+  };
+```
+
+Now we still need to add an icon to the registry, but then the extractor is finished.
+nix-topology supports svg, png and jpeg files, but we prefer SVG wherever possible.
+Usually you should be able to find the original logo of any project in their main repository
+on GitHub by searching for `.svg` by pressing <kbd>t</kbd>.
+
+But before we put it in `icons/services/<service_name>.svg`, we should optimize the svg
+and make sure it has a square `viewBox="..."` property set. For this I recommend passing it through
+`scour` and `svgo` once, this will do all of the work automatically, except for making sure that the
+logo is square:
+
+```bash
+nix-shell -p nodePackages.svgo scour
+scour --enable-viewboxing -i original.svg -o tmp.svg
+svgo -i tmp.svg -o service_name.svg
+```
+
+If you open the file and see a viewBox like `viewBox="0 0 100 100"`, then you are ready to go.
+The actual numbers don't matter, but the last two (width and height) should be the same. If they
+are not, open the file in any svg editor of your liking, for example Inkscape or [boxy-svg.com](https://boxy-svg.com/)
+and make it square manually. (In theory you can also just increase the smaller number and `x` or `y` by half of that
+in the viewBox by hand. Run it through `svgo` another time and you are all set.
+
+## Adding an example
+
+Examples are currently our tests. They are automatically built together with the documentation
+and the rendered result is also included in the docs. If you have made a complex extractor,
+you might want to test it by creating a new example.
+
+All you need to do for that to happen is to create a `flake.nix` in a new example folder,
+for example `examples/foo/flake.nix`. Just copy the simple example and start from there.
+The flake should be a regular flake containing `nixosConfigurations`, just like what a user would
+write. Beware that you currently cannot add inputs to that flake, let me know if you need that.
+
+To build the example, just build the documentation:
+
+```bash
+nix build .#docs`
+```

docs/src/architecture/extractors.md → docs/src/internals/extractors.md

@@ -25,3 +25,4 @@ in
 ```
 
 If you want to add support for new services, feel free to create a PR. Contributions are wholeheartedly welcome!
+There's more information in the [Development Chapter](./development.html).

docs/src/intro.md

@@ -31,6 +31,7 @@ Maybe it will be useful for somebody else, too.
 
 Contributions are whole-heartedly welcome! Please feel free to suggest new features,
 implement extractors, other stuff, or generally help out if you'd like. We'd be happy to have you.
+There's more information in [CONTRIBUTING.md](https://github.com/oddlama/nix-topology/CONTRIBUTING.md) and the [Development Chapter](./development.html) in the docs.
 
 ## 📜 License