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
This commit is contained in:
Vincent Ambo 2019-08-04 22:38:51 +01:00 committed by Vincent Ambo
parent 099c99b7ad
commit 7c41a7a872
11 changed files with 97 additions and 108 deletions

2
tools/nixery/.gitattributes vendored Normal file
View file

@ -0,0 +1,2 @@
# Ignore stylesheet modifications for the book in Linguist stats
*.css linguist-detectable=false

1
tools/nixery/docs/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
book

View file

@ -0,0 +1,8 @@
[book]
authors = ["Vincent Ambo <tazjin@google.com>"]
language = "en"
multilingual = false
src = "src"
[output.html]
additional-css = ["theme/nixery.css"]

View file

@ -0,0 +1,4 @@
# Summary
- [Nixery](./nixery.md)
- [Nix, the language](./nix-1p.md)

View file

@ -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

View file

Before

Width:  |  Height:  |  Size: 190 KiB

After

Width:  |  Height:  |  Size: 190 KiB

View file

@ -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

BIN
tools/nixery/docs/theme/favicon.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 16 KiB

3
tools/nixery/docs/theme/nixery.css vendored Normal file
View file

@ -0,0 +1,3 @@
h2, h3 {
margin-top: 1em;
}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 164 KiB

View file

@ -1,108 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Nixery</title>
<style>
body {
margin: 40px auto;
max-width: 650px;
line-height: 1.6;
font-size: 18px;
color: #444;
padding: 010px
}
.logo {
max-width: 650px;
}
h1, h2, h3 {
line-height: 1.2
}
</style>
</head>
<body>
<header>
<div align="center">
<img class="logo" src="nixery-logo.png">
</div>
<aside>ad-hoc container images - powered by <a href="https://nixos.org/nix/">Nix</a></aside>
<hr>
</header>
<p>
This is an instance
of <a href="https://github.com/google/nixery">Nixery</a>, 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.
</p>
<p>
Nix is also responsible for the creation of the container images
themselves. To do this it uses an interesting layering strategy
described in
<a href="https://grahamc.com/blog/nix-and-layered-docker-images">this blog post</a>.
</p>
<h3>How does it work?</h3>
<p>
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 <code>emacs</code> you could pull it as such:
</p>
<p>
<code>nixery.dev/shell/emacs25-nox</code>
</p>
<p>
Image tags are currently ignored. Every package name needs to
correspond to a key in the
<a href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix">nixpkgs package set</a>.
</p>
<p>
The special meta-package <i>shell </i> provides default packages
you would expect in an interactive environment (such as an
interactively configured bash). If you use this package
you <b>must</b> specify it as the first package in an image.
</p>
<h3>FAQ</h3>
<ul>
<li>
<strong>Where is the source code for this?</strong>
<br>
Over <a href="https://github.com/google/nixery">on Github</a>.
</li>
<li>
<strong>Which revision of <code>nixpkgs</code> is used?</strong>
<br>
Nixery imports a Nix channel
via <code>builtins.fetchTarball</code>. Currently the channel
to which this instance is pinned is NixOS 19.03.
</li>
<li>
<strong>Is this an official Google project?</strong>
<br>
<strong>No.</strong> Nixery is not officially supported by
Google.
</li>
<li>
<strong>Can I depend on the demo instance in production?</strong>
<br>
<strong>No.</strong> The demo instance is just a demo. It
might go down, move, or disappear entirely at any point.
<br>
To make use of Nixery in your project, please deploy a private
instance. Stay tuned for instructions for how to do this on
GKE.
</li>
<li>
<strong>Who made this?</strong>
<br>
<a href="https://github.com/tazjin">tazjin</a>
</li>
</ul>
</body>
</html>