From 9ce7b78c1f864fcfda7a1c6255757f32d12c4a09 Mon Sep 17 00:00:00 2001 From: DavHau Date: Mon, 18 Jul 2022 18:58:36 +0200 Subject: [PATCH] Revert "refactor: readme/docs" --- README.md | 125 +++++++++++++++++++++--- docs/src/SUMMARY.md | 2 - docs/src/guides/quick-start.md | 98 ------------------- docs/src/intro/presentation-oct-2021.md | 4 - 4 files changed, 114 insertions(+), 115 deletions(-) delete mode 100644 docs/src/guides/quick-start.md delete mode 100644 docs/src/intro/presentation-oct-2021.md diff --git a/README.md b/README.md index 69e5c7af..76f2f0a8 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,6 @@ !!! Warning: dream2nix is unstable software. While simple UX is one of our main focus points, the APIs are still under development. Do expect changes that will break your setup. -Jump to: -- [Quick Start](https://nix-community.github.io/dream2nix/guides/quick-start.html) -- [Documentation](https://nix-community.github.io/dream2nix) - dream2nix is a framework for automatically converting packages from other build systems to nix. It focuses on the following aspects: @@ -30,12 +26,123 @@ The goal of this project is to create a standardized, generic, modular framework The intention is to integrate many existing 2nix converters into this framework, thereby improving many of the previously named aspects and providing a unified UX for all 2nix solutions. +### Test the experimental version of dream2nix + +(Currently only nodejs and rust packaging is supported) + +1. Make sure you use a nix version >= 2.4 and have `experimental-features = "nix-command flakes"` set. +1. Navigate to to the project intended to be packaged and initialize a dream2nix flake: + ```command + cd ./my-project + nix flake init -t github:nix-community/dream2nix#simple + ``` +1. List the packages that can be built + ```command + nix flake show + ``` + + +Minimal Example `flake.nix`: +```nix +{ + inputs.dream2nix.url = "github:nix-community/dream2nix"; + outputs = { self, dream2nix }: + dream2nix.lib.makeFlakeOutputs { + systems = ["x86_64-linux"]; + config.projectRoot = ./.; + source = ./.; + }; +} +``` + +Extensive Example `flake.nix`: +```nix +{ + inputs.dream2nix.url = "github:nix-community/dream2nix"; + outputs = { self, dream2nix }: + dream2nix.lib.makeFlakeOutputs { + systems = ["x86_64-linux"]; + config.projectRoot = ./.; + + source = ./.; + + # Configure the behavior of dream2nix when translating projects. + # A setting applies to all discovered projects if `filter` is unset, + # or just to a subset or projects if `filter` is used. + settings = [ + # prefer aggregated source fetching (large FODs) + { + aggregate = true; + } + # for all impure nodejs projects with just a `package.json`, + # add arguments for the `package-json` translator + { + filter = project: project.translator == "package-json"; + subsystemInfo.npmArgs = "--legacy-peer-deps"; + subsystemInfo.nodejs = 18; + } + ]; + + # configure package builds via overrides + # (see docs for override system below) + packageOverrides = { + # name of the package + package-name = { + # name the override + add-pre-build-steps = { + # override attributes + preBuild = "..."; + # update attributes + buildInputs = old: old ++ [pkgs.hello]; + }; + }; + }; + + # Inject missing dependencies + inject = { + # Make foo depend on bar and baz + # from + foo."6.4.1" = [ + # to + ["bar" "13.2.0"] + ["baz" "1.0.0"] + ]; + # dependencies with @ and slash require quoting + # the format is the one that is in the lockfile + "@tiptap/extension-code"."2.0.0-beta.26" = [ + ["@tiptap/core" "2.0.0-beta.174"] + ]; + }; + + # add sources for `bar` and `baz` + sourceOverrides = oldSources: { + bar."13.2.0" = builtins.fetchTarball {url = ""; sha256 = "";}; + baz."1.0.0" = builtins.fetchTarball {url = ""; sha256 = "";}; + }; + }; +} +``` + +An example for instancing dream2nix per pkgs and using it to create outputs can be found at [`examples/d2n-init-pkgs`](./examples/d2n-init-pkgs/flake.nix). + ### Documentation -Documentation can be found at [nix-community.github.io/dream2nix](https://nix-community.github.io/dream2nix). +Documentation for `main` branch is deployed to https://nix-community.github.io/dream2nix. + +A CLI app is available if you want to read documentation in your terminal. +The app is available as `d2n-docs` if you enter the development shell, otherwise you can access it with `nix run .#docs`. +`d2n-docs` can be used to access all available documentation. +To access a specific document you can use `d2n-docs doc-name` where `doc-name` is the name of the document. +For example, to access Rust subsystem documentation, you can use `d2n-docs rust`. + +You can also build documentation by running `nix build .#docs`. +Or by entering the development shell (`nix develop`) and running `mdbook build docs`. + +### Watch the presentation + +(The code examples of the presentation are outdated) +[![dream2nix - A generic framework for 2nix tools](https://gist.githubusercontent.com/DavHau/755fed3774e89c0b9b8953a0a25309fa/raw/3c8b2c56f5fca3bf5c343ffc179136eef39d4d6a/dream2nix-youtube-talk.png)](https://www.youtube.com/watch?v=jqCfHMvCsfQ) -The documentation is also available in your terminal inside the dream2nix dev shell via `d2n-docs [keyword]` or by running: -`nix run github:nix-community/dream2nix#docs [keyword]` ### Funding This project receives financial support by [NLNet](https://nlnet.nl/) as part of the [NGI Assure Programme](https://nlnet.nl/assure/) funded by the European Commission. @@ -46,7 +153,3 @@ If your organization wants to support the project with extra funding in order to matrix: https://matrix.to/#/#dream2nix:nixos.org -### Watch the presentation - -(The code examples of the presentation are outdated) -[![dream2nix - A generic framework for 2nix tools](https://gist.githubusercontent.com/DavHau/755fed3774e89c0b9b8953a0a25309fa/raw/3c8b2c56f5fca3bf5c343ffc179136eef39d4d6a/dream2nix-youtube-talk.png)](https://www.youtube.com/watch?v=jqCfHMvCsfQ) diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 6960fccb..8990ffe5 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -2,7 +2,6 @@ - [Introduction](./intro.md) # Guides -- [Quick Start](./guides/quick-start.md) - [Python: getting started in 10 minutes](./guides/getting-started-python.md) # Subsystems - [Rust](./subsystems/rust.md) @@ -14,7 +13,6 @@ - [Override system](./intro/override-system.md) - [Translators](./intro/translators.md) - [Indexers](./intro/indexers.md) -- [Presentation Oct. 2021](./intro/presentation-oct-2021.md) # Contributing diff --git a/docs/src/guides/quick-start.md b/docs/src/guides/quick-start.md deleted file mode 100644 index 20ea6b28..00000000 --- a/docs/src/guides/quick-start.md +++ /dev/null @@ -1,98 +0,0 @@ -## Test the experimental version of dream2nix - -(Currently only nodejs, python and rust packaging is supported) - -1. Make sure you use a nix version >= 2.4 and have `experimental-features = "nix-command flakes"` set. -1. Navigate to to the project intended to be packaged and initialize a dream2nix flake: - ```command - cd ./my-project - nix flake init -t github:nix-community/dream2nix#simple - ``` -1. List the packages that can be built - ```command - nix flake show - ``` - - -Minimal Example `flake.nix`: -```nix -{ - inputs.dream2nix.url = "github:nix-community/dream2nix"; - outputs = { self, dream2nix }: - dream2nix.lib.makeFlakeOutputs { - systems = ["x86_64-linux"]; - config.projectRoot = ./.; - source = ./.; - }; -} -``` - -Extensive Example `flake.nix`: -```nix -{ - inputs.dream2nix.url = "github:nix-community/dream2nix"; - outputs = { self, dream2nix }: - dream2nix.lib.makeFlakeOutputs { - systems = ["x86_64-linux"]; - config.projectRoot = ./.; - - source = ./.; - - # Configure the behavior of dream2nix when translating projects. - # A setting applies to all discovered projects if `filter` is unset, - # or just to a subset or projects if `filter` is used. - settings = [ - # prefer aggregated source fetching (large FODs) - { - aggregate = true; - } - # for all impure nodejs projects with just a `package.json`, - # add arguments for the `package-json` translator - { - filter = project: project.translator == "package-json"; - subsystemInfo.npmArgs = "--legacy-peer-deps"; - subsystemInfo.nodejs = 18; - } - ]; - - # configure package builds via overrides - # (see docs for override system below) - packageOverrides = { - # name of the package - package-name = { - # name the override - add-pre-build-steps = { - # override attributes - preBuild = "..."; - # update attributes - buildInputs = old: old ++ [pkgs.hello]; - }; - }; - }; - - # Inject missing dependencies - inject = { - # Make foo depend on bar and baz - # from - foo."6.4.1" = [ - # to - ["bar" "13.2.0"] - ["baz" "1.0.0"] - ]; - # dependencies with @ and slash require quoting - # the format is the one that is in the lockfile - "@tiptap/extension-code"."2.0.0-beta.26" = [ - ["@tiptap/core" "2.0.0-beta.174"] - ]; - }; - - # add sources for `bar` and `baz` - sourceOverrides = oldSources: { - bar."13.2.0" = builtins.fetchTarball {url = ""; sha256 = "";}; - baz."1.0.0" = builtins.fetchTarball {url = ""; sha256 = "";}; - }; - }; -} -``` - -An example for instancing dream2nix per pkgs and using it to create outputs can be found at [`examples/d2n-init-pkgs`](./examples/d2n-init-pkgs/flake.nix). diff --git a/docs/src/intro/presentation-oct-2021.md b/docs/src/intro/presentation-oct-2021.md deleted file mode 100644 index d92746bc..00000000 --- a/docs/src/intro/presentation-oct-2021.md +++ /dev/null @@ -1,4 +0,0 @@ -### Watch the presentation - -(The code examples of the presentation are outdated) -[![dream2nix - A generic framework for 2nix tools](https://gist.githubusercontent.com/DavHau/755fed3774e89c0b9b8953a0a25309fa/raw/3c8b2c56f5fca3bf5c343ffc179136eef39d4d6a/dream2nix-youtube-talk.png)](https://www.youtube.com/watch?v=jqCfHMvCsfQ)