From 7c41a7a8723c8bd6606c0c2f3fed3a546f1efb24 Mon Sep 17 00:00:00 2001 From: Vincent Ambo Date: Sun, 4 Aug 2019 22:38:51 +0100 Subject: docs: Replace static page with mdBook site Uses mdBook[1] to generate a documentation overview page instead of the previous HTML site. This makes it possible to add more elaborate documentation without having to deal with finicky markup. [1]: https://github.com/rust-lang-nursery/mdBook --- tools/nixery/.gitattributes | 2 + tools/nixery/docs/.gitignore | 1 + tools/nixery/docs/book.toml | 8 +++ tools/nixery/docs/src/SUMMARY.md | 4 ++ tools/nixery/docs/src/nix-1p.md | 2 + tools/nixery/docs/src/nixery-logo.png | Bin 0 -> 194098 bytes tools/nixery/docs/src/nixery.md | 77 ++++++++++++++++++++++++ tools/nixery/docs/theme/favicon.png | Bin 0 -> 16053 bytes tools/nixery/docs/theme/nixery.css | 3 + tools/nixery/static/favicon.ico | Bin 167584 -> 0 bytes tools/nixery/static/index.html | 108 ---------------------------------- tools/nixery/static/nixery-logo.png | Bin 194098 -> 0 bytes 12 files changed, 97 insertions(+), 108 deletions(-) create mode 100644 tools/nixery/.gitattributes create mode 100644 tools/nixery/docs/.gitignore create mode 100644 tools/nixery/docs/book.toml create mode 100644 tools/nixery/docs/src/SUMMARY.md create mode 100644 tools/nixery/docs/src/nix-1p.md create mode 100644 tools/nixery/docs/src/nixery-logo.png create mode 100644 tools/nixery/docs/src/nixery.md create mode 100644 tools/nixery/docs/theme/favicon.png create mode 100644 tools/nixery/docs/theme/nixery.css delete mode 100644 tools/nixery/static/favicon.ico delete mode 100644 tools/nixery/static/index.html delete mode 100644 tools/nixery/static/nixery-logo.png (limited to 'tools') diff --git a/tools/nixery/.gitattributes b/tools/nixery/.gitattributes new file mode 100644 index 000000000000..74464db942e9 --- /dev/null +++ b/tools/nixery/.gitattributes @@ -0,0 +1,2 @@ +# Ignore stylesheet modifications for the book in Linguist stats +*.css linguist-detectable=false diff --git a/tools/nixery/docs/.gitignore b/tools/nixery/docs/.gitignore new file mode 100644 index 000000000000..7585238efedf --- /dev/null +++ b/tools/nixery/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/tools/nixery/docs/book.toml b/tools/nixery/docs/book.toml new file mode 100644 index 000000000000..bf6ccbb27f35 --- /dev/null +++ b/tools/nixery/docs/book.toml @@ -0,0 +1,8 @@ +[book] +authors = ["Vincent Ambo "] +language = "en" +multilingual = false +src = "src" + +[output.html] +additional-css = ["theme/nixery.css"] diff --git a/tools/nixery/docs/src/SUMMARY.md b/tools/nixery/docs/src/SUMMARY.md new file mode 100644 index 000000000000..5d680b82e8d9 --- /dev/null +++ b/tools/nixery/docs/src/SUMMARY.md @@ -0,0 +1,4 @@ +# Summary + +- [Nixery](./nixery.md) +- [Nix, the language](./nix-1p.md) diff --git a/tools/nixery/docs/src/nix-1p.md b/tools/nixery/docs/src/nix-1p.md new file mode 100644 index 000000000000..a21234150fc7 --- /dev/null +++ b/tools/nixery/docs/src/nix-1p.md @@ -0,0 +1,2 @@ +This page is a placeholder. During the build process, it is replaced by the +actual `nix-1p` guide from https://github.com/tazjin/nix-1p diff --git a/tools/nixery/docs/src/nixery-logo.png b/tools/nixery/docs/src/nixery-logo.png new file mode 100644 index 000000000000..fcf77df3d6a9 Binary files /dev/null and b/tools/nixery/docs/src/nixery-logo.png differ diff --git a/tools/nixery/docs/src/nixery.md b/tools/nixery/docs/src/nixery.md new file mode 100644 index 000000000000..d3d1911d2880 --- /dev/null +++ b/tools/nixery/docs/src/nixery.md @@ -0,0 +1,77 @@ +![Nixery](./nixery-logo.png) + +------------ + +Welcome to this instance of [Nixery][]. It provides ad-hoc container images that +contain packages from the [Nix][] package manager. Images with arbitrary +packages can be requested via the image name. + +Nix not only provides the packages to include in the images, but also builds the +images themselves by using an interesting layering strategy described in [this +blog post][layers]. + +## Quick start + +Simply pull an image from this registry, separating each package you want +included by a slash: + + docker pull nixery.dev/shell/git/htop + +This gives you an image with `git`, `htop` and an interactively configured +shell. You could run it like this: + + docker run -ti nixery.dev/shell/git/htop bash + +Each path segment corresponds either to a key in the Nix package set, or a +meta-package that automatically expands to several other packages. + +Meta-packages **must** be the first path component if they are used. Currently +the only meta-package is `shell`, which provides a `bash`-shell with interactive +configuration and standard tools like `coreutils`. + +**Tip:** When pulling from a private Nixery instance, replace `nixery.dev` in +the above examples with your registry address. + +## FAQ + +If you have a question that is not answered here, feel free to file an issue on +Github so that we can get it included in this section. The volume of questions +is quite low, thus by definition your question is already frequently asked. + +### Where is the source code for this? + +Over [on Github][Nixery]. It is licensed under the Apache 2.0 license. Consult +the documentation entries in the sidebar for information on how to set up your +own instance of Nixery. + +### Which revision of `nixpkgs` is used for the builds? + +The instance at `nixery.dev` tracks a recent NixOS channel, currently NixOS +19.03. The channel is updated several times a day. + +Private registries might be configured to track a different channel (such as +`nixos-unstable`) or even track a git repository with custom packages. + +### Is this an official Google project? + +**No.** Nixery is not officially supported by Google. + +### Should I depend on `nixery.dev` in production? + +While we appreciate the enthusiasm, if you would like to use Nixery in your +production project we recommend setting up a private instance. The public Nixery +at `nixery.dev` is run on a best-effort basis and we make no guarantees about +availability. + +### Who made this? + +Nixery was written mostly by [tazjin][]. + +[grahamc][] authored the image layering strategy. Many people have contributed +to Nix over time, maybe you could become one of them? + +[Nixery]: https://github.com/google/nixery +[Nix]: https://nixos.org/nix +[layers]: https://grahamc.com/blog/nix-and-layered-docker-images +[tazjin]: https://github.com/tazjin +[grahamc]: https://github.com/grahamc diff --git a/tools/nixery/docs/theme/favicon.png b/tools/nixery/docs/theme/favicon.png new file mode 100644 index 000000000000..f510bde197ac Binary files /dev/null and b/tools/nixery/docs/theme/favicon.png differ diff --git a/tools/nixery/docs/theme/nixery.css b/tools/nixery/docs/theme/nixery.css new file mode 100644 index 000000000000..c240e693d550 --- /dev/null +++ b/tools/nixery/docs/theme/nixery.css @@ -0,0 +1,3 @@ +h2, h3 { + margin-top: 1em; +} diff --git a/tools/nixery/static/favicon.ico b/tools/nixery/static/favicon.ico deleted file mode 100644 index 7523e8513950..000000000000 Binary files a/tools/nixery/static/favicon.ico and /dev/null differ diff --git a/tools/nixery/static/index.html b/tools/nixery/static/index.html deleted file mode 100644 index 24aa879a535d..000000000000 --- a/tools/nixery/static/index.html +++ /dev/null @@ -1,108 +0,0 @@ - - - - - - Nixery - - - -
-
- -
- -
-
- -

- This is an instance - of Nixery, which - provides the ability to pull ad-hoc container images from a - Docker-compatible registry server. The image names specify the - contents the image should contain, which are then retrieved and - built by the Nix package manager. -

-

- Nix is also responsible for the creation of the container images - themselves. To do this it uses an interesting layering strategy - described in - this blog post. -

-

How does it work?

-

- Simply point your local Docker installation (or other compatible - registry client) at Nixery and ask for an image with the - contents you desire. Image contents are path separated in the - name, so for example if you needed an image that contains a - shell and emacs you could pull it as such: -

-

- nixery.dev/shell/emacs25-nox -

-

- Image tags are currently ignored. Every package name needs to - correspond to a key in the - nixpkgs package set. -

-

- The special meta-package shell provides default packages - you would expect in an interactive environment (such as an - interactively configured bash). If you use this package - you must specify it as the first package in an image. -

-

FAQ

- - - diff --git a/tools/nixery/static/nixery-logo.png b/tools/nixery/static/nixery-logo.png deleted file mode 100644 index fcf77df3d6a9..000000000000 Binary files a/tools/nixery/static/nixery-logo.png and /dev/null differ -- cgit 1.4.1