feat: add mkdocs and auto-document nixos module types (#147)

.gitignore

@@ -5,4 +5,7 @@
 /result*
 
 # IDE
-.idea/
+.idea/
+
+# Generated docs files
+docs/modules/reference.md

LICENSE.md

@@ -0,0 +1 @@
+docs/license.md

README.md

@@ -16,7 +16,7 @@
 
 This is an experimental Nix project for integrating the most interesting / important projects in the Ethereum ecosystem as Nix packages / NixOS modules.
 
-Many of the packages found here will be added to `nixpkgs` repository once they're stable / mature enough. But for some others, more experimental ones, they can reside here.
+Many of the packages found ~~~~here will be added to `nixpkgs` repository once they're stable / mature enough. But for some others, more experimental ones, they can reside here.
 
 This project is developed entirely in [Nix Flakes](https://nixos.wiki/wiki/Flakes).
 
@@ -93,13 +93,17 @@ Optional: [install direnv](https://github.com/direnv/direnv#basic-installation),
 
 ## Development
 
-#### Running tests
+### Docs
+
+To serve the docs run `, docs`. You can edit the docs in `./docs`.
+
+### Running tests
 
 To run all tests you can use `nix flake check`, it will build all packages and run all tests.
 
 To execute a specific test you can use `, test -h` which will provide more information.
 
-#### Formatting
+### Formatting
 
 You can manually format using the `format` command like so:
 

docs/contributing.md

@@ -0,0 +1,136 @@
+# Contribution Guidelines
+
+This file contains instructions that will help you make a contribution.
+
+## Licensing
+
+The Ethereum.nix packages, modules and this user guide are licensed under the [MIT license](license.md).
+
+## Before you contribute
+
+Here you can take a look at the [existing issues](https://github.com/nix-community/ethereum.nix/issues). Feel free to contribute, but make sure you have a [GitHub account](https://github.com/join) first :) .
+
+If you're new to open source, please read GitHub's guide on [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/). It's a quick read, and it's a great way to introduce yourself to how things work behind the scenes in open-source projects.
+
+Before sending a pull request, make sure that you've read all the guidelines. If you don't understand something, please [state your question clearly in an issue](https://github.com/nix-community/ethereum.nix/issues/new).
+
+## Creating an issue
+
+If you need to create an issue, make sure to clearly describe it, including:
+
+- The steps to reproduce it if it's a bug
+- The version of ethereum.nix used
+
+## Making changes
+
+If you want to introduce changes to the project, please follow these steps:
+
+- Fork the repository on GitHub
+- Create a branch on your fork. Don't commit directly to main
+- Add the necessary tests for your changes
+- Push your changes to the branch in your repository fork
+- Submit a pull request to the original repository
+
+Make sure you based your commits on logical and atomic units!
+
+## Examples of git history
+
+Git history that we want to have:
+
+Git history that we are trying to avoid:
+
+<details>
+
+<summary>Git history that we want to have</summary>
+
+```
+
+*   e3ed88b (HEAD -> contribution-guide, upstream/main, origin/main, origin/HEAD, main) Merge pull request #470 from zimbatm/fix_lru_cache
+
+|\
+
+| * 1ab7d9f Use rayon for multithreading command
+
+|/
+
+*   e9c5bb4 Merge pull request #468 from zimbatm/multithread
+
+|\
+
+| * de2d6cf Add lint property for Formatter struct
+
+| * cd2ed17 Fix impl on Formatter get_command() function
+
+|/
+
+*   028c344 Merge pull request #465 from rayon/0.15.0-release
+
+|\
+
+| * 7b619d6 0.15.0 release
+
+|/
+
+*   acdf7df Merge pull request #463 from zimbatm/support-multi-part-namespaces
+
+```
+
+</details>
+
+<details>
+
+<summary>Git history that we are <b>trying</b> to avoid:</summary>
+
+```
+
+*   4c8aca8 Merge pull request #120 from zimbatm/add-rayon
+
+|\
+
+| * fc2b449 use rayon for engine now
+
+| * 2304683 add rayon config
+
+| * 5285bd3 bump base image to F30
+
+* |   4d0fbe2 Merge pull request #114 from rizary/create_method_create_release
+
+|\ \
+
+| * | 36a9396 test changed
+
+| * | 22f681d method create release for github created
+
+* | |   2ef4ea1 Merge pull request #119 from rizary/config.rs
+
+|\ \ \
+
+| |/ /
+
+|/| |
+
+| * | 5f1b8f0 unused functions removed
+
+* | |   a93c361 Merge pull request #117 from zimbatm/add-getreleases-to-abstract
+
+|\ \ \
+
+| |/ /
+
+|/| |
+
+| * | 0a97236 add get_releses for Cargo
+
+| * | 55e4c57 add get_releases/get_release into engine.rs
+
+|/ /
+
+* |   badeddd Merge pull request #101 from zimbatm/extreme-cachin
+
+```
+
+</details>
+
+Additionally, it's always good to work on improving documentation and adding examples.
+
+Thank you for considering contributing to `ethereum.nix`.

docs/index.md

@@ -0,0 +1,10 @@
+# About the Project
+
+`Ethereum.nix` is a collection of [Nix](https://nixos.org) packages and [NixOS](https://nixos.wiki/wiki/NixOS_modules) modules
+designed to make it easier to operate [Ethereum](https://ethereum.org) related services and infrastructure.
+
+## Background
+
+In the beginning `Ethereum.nix` was a playground for [Aldo Borrero](https://aldoborrero.com/) to experiment with _nix'ifying_
+Ethereum related processes. Since then, it has a grown into an ever-increasing number of packages and modules targeted towards
+streamlining day-to-day operations across a variety of different projects.

flake.nix

@@ -65,6 +65,7 @@
           ./nix
           ./packages
           ./modules
+          ./mkdocs.nix
         ];
         systems = [
           "x86_64-linux"

mkdocs.nix

@@ -0,0 +1,46 @@
+{
+  perSystem = {
+    lib,
+    pkgs,
+    ...
+  }: let
+    inherit (pkgs) stdenv mkdocs python310Packages;
+    reference-doc = pkgs.callPackage ./reference.nix {inherit lib;};
+  in {
+    packages.docs = stdenv.mkDerivation {
+      src = ./.;
+      name = "ethereum-nix-docs";
+
+      buildInput = [reference-doc];
+      nativeBuildInputs = [mkdocs python310Packages.mkdocs-material];
+
+      buildPhase = ''
+        ln -s ${reference-doc} ./docs/reference.md
+        ls -al ./docs
+        cat ./docs/modules/reference.md
+        mkdocs build
+      '';
+
+      installPhase = ''
+        mv site $out
+      '';
+    };
+
+    mission-control.scripts = let
+      category = "Docs";
+    in
+      with lib; {
+        docs = {
+          inherit category;
+          description = "Serve docs";
+          exec = ''
+            # link in options reference
+            rm -f ./docs/modules/reference.md
+            ln -s ${reference-doc} ./docs/modules/reference.md
+
+            mkdocs serve
+          '';
+        };
+      };
+  };
+}

mkdocs.yml

@@ -0,0 +1,59 @@
+site_name: Ethereum.nix
+site_description: Nix packages and NixOS modules for the Ethereum ecosystem
+site_url: https://nix-community.github.io/ethereum.nix
+
+repo_url: https://github.com/nix-community/ethereum.nix
+edit_uri: edit/main/docs
+
+theme:
+  name: material
+  logo: assets/logo.svg
+  favicon: assets/favicon.png
+
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    - scheme: default
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/brightness-5
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: blue grey
+      accent: amber
+      toggle:
+        icon: material/brightness-2
+        name: Switch to light mode
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+
+    - navigation.sections
+    - navigation.top
+    - toc.follow
+    - content.action.edit
+    - content.action.view
+    - search.suggest
+    - search.highlight
+    - search.share
+
+
+
+extra:
+  homepage: https://nix-community.github.io/ethereum.nix
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/nix-community/ethereum.nix
+      name: Ethereum.nix on Github
+  generator: false # hide the line "Made with Material for MkDocs"
+
+copyright: Copyright © 41North and Ethereum.nix contributors