mirrors/flake-parts
1
0
Fork 0
mirror of https://github.com/hercules-ci/flake-parts.git synced 2024-12-14 11:47:31 +00:00
Code Activity

Use mdbook for site, improve docs and readme

Browse source
This commit is contained in:
Robert Hensing 2022-11-11 12:16:35 +01:00
parent 5bbb5e579d
commit 9de9af5460
12 changed files with 227 additions and 128 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
README.md
View file

@ -3,7 +3,12 @@
_Core of a distributed framework for writing Nix Flakes._
`flake-parts` provides the options that represent standard flake attributes and establishes a way of working with `system`. Opinionated features are provided by an ecosystem of modules that you can import.
`flake-parts` provides the options that represent standard flake attributes
and establishes a way of working with `system`.
Opinionated features are provided by an ecosystem of modules that you can import.
`flake-parts` _itself_ has the goal to be a minimal mirror of the Nix flake schema.
Used by itself, it is very lightweight.
# Why Modules?
@ -16,8 +21,20 @@ module system has done for NixOS configurations.
Unlike NixOS, but following Flakes' spirit, `flake-parts` is not a
monorepo with the implied goal of absorbing all of open source, but rather
a single module that other repositories can build upon, while ensuring a
baseline level of compatibility: which core attribute make up a flake and
how these are represented as module options.
baseline level of compatibility: the core attributes that constitute a flake.
# Features
- Split your `flake.nix` into focused units, each in their own file.
- Take care of [system](./system.md).
- Allow users of your library flake to easily integrate your generated flake outputs
into their flake.
- Reuse project logic written by others
<!-- end_of_intro -->
# Getting Started

1
dev/flake-module.nix
View file

@ -16,6 +16,7 @@
pkgs.hci
pkgs.netlify-cli
pkgs.pandoc
pkgs.mdbook
];
shellHook = ''
${config.pre-commit.installationScript}

1
site/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
book

6
site/book.toml Normal file
View file

@ -0,0 +1,6 @@
[book]
authors = ["Robert Hensing", "Various module authors"]
language = "en"
multilingual = false
src = "src"
title = "flake-parts"

122
site/flake-module.nix
View file

@ -31,9 +31,9 @@
then opt // { visible = false; }
else opt // { inherit declarations; };
optionsDoc = { sourceName, baseUrl, sourcePath, title }: pkgs.runCommand "${sourceName}-doc"
optionsDoc = { sourceName, baseUrl, sourcePath, title }: pkgs.runCommand "option-doc-${sourceName}"
{
nativeBuildInputs = [ pkgs.libxslt.bin ];
nativeBuildInputs = [ pkgs.libxslt.bin pkgs.pandoc ];
inputDoc = (pkgs.nixosOptionsDoc {
options = opts;
documentType = "none";
@ -46,74 +46,74 @@
inherit title;
} ''
xsltproc --stringparam title "$title" \
-o $out ${./options.xsl} \
-o options.db.xml ${./options.xsl} \
"$inputDoc"
mkdir $out
pandoc --verbose --from docbook --to html options.db.xml >$out/options.md;
'';
repos = {
flake-parts = {
title = "Core Options";
sourceName = "flake-parts";
baseUrl = "https://github.com/hercules-ci/flake-parts/blob/main";
sourcePath = ../.;
};
pre-commit-hooks-nix = {
title = "pre-commit-hooks.nix";
sourceName = "pre-commit-hooks.nix";
baseUrl = "https://github.com/hercules-ci/pre-commit-hooks.nix/blob/flakeModule";
sourcePath = inputs.pre-commit-hooks-nix;
};
hercules-ci-effects = {
title = "hercules-ci-effects";
sourceName = "hercules-ci-effects";
baseUrl = "https://github.com/hercules-ci/hercules-ci-effects/blob/master";
sourcePath = inputs.hercules-ci-effects;
};
};
in
{
packages = {
siteContent = pkgs.stdenvNoCC.mkDerivation {
name = "site";
nativeBuildInputs = [ pkgs.pandoc pkgs.libxslt.bin ];
src = lib.cleanSourceWith {
filter = path: type:
path == ./.
|| baseNameOf path == "index.html";
src = ./.;
};
coreOptions = optionsDoc {
title = "Core Options";
sourceName = "flake-parts";
baseUrl = "https://github.com/hercules-ci/flake-parts/blob/main";
sourcePath = ../.;
};
# TODO make this a dynamic input
pre_commit_hooks_nixOptions = optionsDoc {
title = "pre-commit-hooks.nix";
sourceName = "pre-commit-hooks.nix";
baseUrl = "https://github.com/hercules-ci/pre-commit-hooks.nix/blob/flakeModule";
sourcePath = inputs.pre-commit-hooks-nix;
};
# TODO make this a dynamic input
hercules_ci_effectsOptions = optionsDoc {
title = "hercules-ci-effects";
sourceName = "hercules-ci-effects";
baseUrl = "https://github.com/hercules-ci/hercules-ci-effects/blob/master";
sourcePath = inputs.hercules-ci-effects;
};
# pandoc
htmlBefore = ''
<html>
<head>
<title>Options</title>
<style type="text/css">
a:target { background-color: rgba(239,255,0,0.5); }
body {
max-width: 40em;
margin-left: auto;
margin-right: auto;
}
</style>
</head>
<body>
'';
htmlAfter = ''
</body>
</html>
'';
nativeBuildInputs = [ pkgs.mdbook ];
src = ./.;
buildPhase = ''
( echo "$htmlBefore";
pandoc --verbose --from docbook --to html5 $coreOptions;
pandoc --verbose --from docbook --to html5 $hercules_ci_effectsOptions;
pandoc --verbose --from docbook --to html5 $pre_commit_hooks_nixOptions;
echo "$htmlAfter"; ) >options.html
'';
installPhase = ''
mkdir -p $out
cp *.html $out/
runHook preBuild
{
while read ln; do
case "$ln" in
*end_of_intro*)
break
;;
*)
echo "$ln"
;;
esac
done
cat src/intro-continued.md
} <${../README.md} >src/README.md
mkdir -p src/options
${lib.concatStringsSep "\n"
(lib.mapAttrsToList
(name: repo: ''
cp '${optionsDoc repo}/options.md' 'src/options/${name}.md'
'')
repos)
}
mdbook build --dest-dir $out
echo '<html><head><script>window.location.pathname = window.location.pathname.replace(/options.html$/, "") + "/options/flake-parts.html"</script></head><body><a href="options/flake-parts.html">to the options</a></body></html>' \
>$out/options.html
runHook postBuild
'';
dontInstall = true;
};
};
};

64
site/index.html
View file

@ -1,64 +0,0 @@
<html>
<head>
<title>flake-parts</title>
</head>
<body>
<h1><code>flake-parts</code></h1>
<p>
Compose flakes with the (NixOS) module system.
</p>
<p>
Testimonials:
</p>
<blockquote>
yeah.. powerful stuff
</blockquote>
<blockquote>
I cannot tell you how freeing the flake-modules concept is<br/>
fucking hell<br/>
I feel like a hipster using it too
</blockquote>
<p>
Learn more:
</p>
<p>
<a href="https://github.com/hercules-ci/flake-parts">GitHub</a>
</p>
<p>
<a href="./options.html">Options Reference</a>
</p>
<p>
<a href="https://github.com/hercules-ci/flake-parts/blob/main/ChangeLog.md">ChangeLog</a>
</p>
<p>
Integrations:
</p>
<ul>
<li><code>github:hercules-ci/hercules-ci-effects</code></li>
<li><code>github:hercules-ci/pre-commit-hooks.nix/flakeModule</code></li>
</ul>
<h2>Write your own integration</h2>
<p>
For a general introduction to modules, you can read <a href="https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules">Writing Modules</a> in the NixOS manual, though it goes into NixOS specifics quite quickly. Instead of <code>services.&ltname>.*</code>, etc, we have our own <a href="./options.html">options</a>.
</p>
<p>
Writing modules in a distributed ecosystem can be a bit different. If you're inclined to write to some other module's options, consider whether those will be loaded and whether your integration idea is always desirable. If it's not always desirable, consider splitting it off into an extra module, e.g. <code>flakeModules.someOther</code>. Otherwise check if it's loaded: <code>lib.optionalAttrs (options?some.other.option)</code>. You can ask <code>@roberth</code> on GitHub.
</p>
</body>
</html>

4
site/options.xsl
View file

@ -14,6 +14,10 @@
<title>
<xsl:value-of select="$title"/>
</title>
<para>Overview:</para>
<xsl:for-each select="db:varlistentry">
<para><link xlink:href="#{db:term/@xml:id}"><xsl:copy-of select="db:term/db:option"/></link></para>
</xsl:for-each>
<xsl:apply-templates />
</chapter>
</xsl:template>

11
site/src/SUMMARY.md Normal file
View file

@ -0,0 +1,11 @@
# Summary
- [Introduction](./README.md)
- [Getting Started](./getting-started.md)
- [Working with `system`](./system.md)
- [Reference Documentation](./module-arguments.md)
- [Module Arguments](./module-arguments.md)
- [Options](./options/flake-parts.md)
- [Core `flake-parts`](./options/flake-parts.md)
- [`hercules-ci-effects`](./options/hercules-ci-effects.md)
- [`pre-commit-hooks.nix`](./options/pre-commit-hooks-nix.md)

38
site/src/getting-started.md Normal file
View file

@ -0,0 +1,38 @@
# Getting Started
## New flake
If your project does not have a flake yet:
```console
nix flake init -t github:hercules-ci/flake-parts
```
## Existing flake
Otherwise, add the input,
```
flake-parts.url = "github:hercules-ci/flake-parts";
```
then slide `mkFlake` between your outputs function head and body,
```
outputs = { self, flake-parts, ... }:
flake-parts.lib.mkFlake { inherit self; } {
flake = {
# Put your original flake attributes here.
};
systems = [
# systems for which you want to build the `perSystem` attributes
"x86_64-linux"
# ...
];
perSystem = { config, ... }: {
};
};
```
Now you can start using the flake-parts options.

7
site/src/intro-continued.md Normal file
View file

@ -0,0 +1,7 @@
<!-- prefaced by the README intro -->
# This documentation
You can find guides and the options reference in the menu (top left).
A site wide search is available by typing `s`.

58
site/src/module-arguments.md Normal file
View file

@ -0,0 +1,58 @@
# Module Arguments
The module system allows modules and submodules to be defined using plain
attribute sets, or functions that return attribute sets. When a module is a
function, various attributes may be passed to it.
# Top-level Module Arguments
Top-level refers to the module passed to `mkFlake`, or any of the modules
imported into it using `imports`.
The standard module system arguments are available in all modules and submodules. These are chiefly `config`, `options`, `lib`.
## `getSystem`
A function from [system](./system.md) string to the `config` of the appropriate `perSystem`.
## `moduleWithSystem`
A function that brings the `perSystem` module arguments.
This allows a module to reference the defining flake without introducing
global variables.
```nix
{ moduleWithSystem, ... }:
{
nixosModules.default = moduleWithSystem (
perSystem@{ config }: # NOTE: only explicit params will be in perSystem
nixos@{ ... }:
{
services.foo.package = perSystem.config.packages.foo;
imports = [ ./nixos-foo.nix ];
}
);
}
```
## `withSystem`
Enter the scope of a system. Worked example:
```nix
{ withSystem, ... }:
{
# perSystem = ...;
nixosConfigurations.foo = withSystem "x86_64-linux" (ctx@{ pkgs, ... }:
pkgs.nixos ({ config, lib, packages, pkgs, ... }: {
_module.args.packages = ctx.config.packages;
imports = [ ./nixos-configuration.nix ];
services.nginx.enable = true;
environment.systemPackages = [
packages.hello
];
}));
}
```

20
site/src/system.md Normal file
View file

@ -0,0 +1,20 @@
# `system`
In Nix, "system" generally refers to the cpu-os string, such as `"x86_64-linux"`.
In Flakes specifically, these strings are used as attribute names, so that the
Nix CLI can find a derivation for the right platform.
Many things, such as packages, can exist on multiple systems. For these, use
the [`perSystem`](options/flake-parts.html#opt-perSystem) submodule.
Other things do not exist on multiple systems. Examples are the configuration
of a specific machine, or a the execution of a deployment. These are not
written in `perSystem`, but in other top-level options, or directly into the
flake outputs' top level (e.g. [`flake.nixosConfigurations`](options/flake-parts.html#opt-flake.nixosConfigurations)).
Such top-level entities typically do need to read packages, etc that are defined
in `perSystem`. Instead of reading them from `config.flake.packages.<system>.<name>`,
it may be more convenient to bring all `perSystem` definitions for a system into
scope, using [`withSystem`](module-arguments.html#withsystem).